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

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

@@ -0,0 +1,57 @@
+import { hasAllFeatures } from '@open-mercato/shared/lib/auth/featureMatch'
+import { hasTier, type DocumentTier } from './permissions'
+
+export type DocumentCapabilities = {
+  canView: boolean
+  canComment: boolean
+  canEdit: boolean
+  canShare: boolean
+  canDelete: boolean
+  canCreate: boolean
+  canManageTemplates: boolean
+  canArchive: boolean
+  canDuplicate: boolean
+}
+
+export type DeriveDocumentCapabilitiesInput = {
+  relationshipTier: DocumentTier | null
+  managerOverride?: boolean
+  archived?: boolean
+  userFeatures: readonly string[]
+}
+
+function hasFeature(userFeatures: readonly string[], feature: string): boolean {
+  return hasAllFeatures([feature], Array.from(userFeatures))
+}
+
+export function hasDocumentsManagerOverride(userFeatures: readonly string[]): boolean {
+  return hasFeature(userFeatures, 'documents.manage')
+}
+
+export function deriveDocumentCapabilities(
+  input: DeriveDocumentCapabilitiesInput,
+): DocumentCapabilities {
+  const managerOverride = input.managerOverride === true
+    && hasDocumentsManagerOverride(input.userFeatures)
+  const hasRelationship = input.relationshipTier !== null || managerOverride
+  const canCommentByTier = managerOverride
+    || hasTier(input.relationshipTier, 'commenter')
+  const canEditByTier = managerOverride
+    || hasTier(input.relationshipTier, 'editor')
+  const canOwnByTier = managerOverride || input.relationshipTier === 'owner'
+  const archived = input.archived === true
+
+  return {
+    canView: hasRelationship && hasFeature(input.userFeatures, 'documents.view'),
+    canComment: !archived && canCommentByTier && hasFeature(input.userFeatures, 'documents.view'),
+    canEdit: !archived && canEditByTier && hasFeature(input.userFeatures, 'documents.edit'),
+    canShare: !archived && canOwnByTier && hasFeature(input.userFeatures, 'documents.share'),
+    canDelete: canOwnByTier && hasFeature(input.userFeatures, 'documents.delete'),
+    canCreate: hasFeature(input.userFeatures, 'documents.create'),
+    canManageTemplates: hasFeature(input.userFeatures, 'documents.templates.manage'),
+    canArchive: canOwnByTier && hasFeature(input.userFeatures, 'documents.edit'),
+    canDuplicate: hasRelationship
+      && hasFeature(input.userFeatures, 'documents.create')
+      && hasFeature(input.userFeatures, 'documents.edit'),
+  }
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Hocuspocus closes every socket of a room with `ResetConnection` (4205) both
+ * when the room only needs to re-authenticate (share/archive changes) and when
+ * its content was replaced server-side (version restore, content reset). The
+ * provider reconnects with the SAME local Y.Doc in both cases — after a
+ * content replacement that stale document would sync straight back into the
+ * freshly loaded room and silently undo the restore. The sidecar therefore
+ * closes content-replaced rooms with this dedicated reason so browsers know to
+ * discard their local document before reconnecting.
+ *
+ * Only the reason is significant. Hocuspocus multiplexes documents over one
+ * socket, so a per-document close reaches the browser as a Close *message*
+ * that the provider surfaces with code 1000 and the server-supplied reason;
+ * the 4205 code is only observed when the socket itself is closed.
+ */
+export const COLLAB_CONTENT_RESET_CLOSE_CODE = 4205
+export const COLLAB_CONTENT_RESET_CLOSE_REASON = 'documents:content-reset'
+export const COLLAB_CONTENT_RESET_CLOSE_EVENT = {
+  code: COLLAB_CONTENT_RESET_CLOSE_CODE,
+  reason: COLLAB_CONTENT_RESET_CLOSE_REASON,
+} as const
+
+export function isCollabContentResetCloseEvent(event: unknown): boolean {
+  if (!event || typeof event !== 'object') return false
+  return (event as { reason?: unknown }).reason === COLLAB_CONTENT_RESET_CLOSE_REASON
+}

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

@@ -0,0 +1,43 @@
+export type CollaborationEndpointOptions = {
+  nodeEnv?: string
+  allowLoopback?: boolean
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  return hostname === 'localhost'
+    || hostname.endsWith('.localhost')
+    || hostname === '::1'
+    || hostname === '::'
+    || hostname === '0.0.0.0'
+    || /^127(?:\.|$)/.test(hostname)
+    || /^::ffff:7f[0-9a-f]{2}:/.test(hostname)
+    || hostname === '::ffff:0:0'
+}
+
+export function resolveDocumentsCollaborationEndpoint(
+  raw = process.env.NEXT_PUBLIC_DOCUMENTS_COLLAB_URL,
+  options: CollaborationEndpointOptions = {},
+): string | null {
+  if (!raw || raw !== raw.trim()) return null
+
+  let endpoint: URL
+  try {
+    endpoint = new URL(raw)
+  } catch {
+    return null
+  }
+
+  const hostname = endpoint.hostname
+    .replace(/^\[|\]$/g, '')
+    .toLowerCase()
+    .replace(/\.$/, '')
+  if (!['ws:', 'wss:'].includes(endpoint.protocol) || !hostname) return null
+
+  const nodeEnv = options.nodeEnv ?? process.env.NODE_ENV
+  const allowLoopback = options.allowLoopback ?? (
+    nodeEnv !== 'production' || process.env.OM_DOCUMENTS_COLLAB_INTEGRATION === '1'
+  )
+  if (!allowLoopback && isLoopbackHostname(hostname)) return null
+
+  return raw
+}

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

@@ -0,0 +1,140 @@
+import { createRequire } from 'node:module'
+import type { JSONContent } from '@tiptap/core'
+import { TiptapTransformer } from '@hocuspocus/transformer'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import * as Y from 'yjs'
+import { deriveContentTextFromHtml } from './contentService'
+import { COLLAB_FRAGMENT_FIELD, getDocumentEditorExtensions } from './editorConfig'
+import { assertDocumentContentResourceLimits } from './resourceLimits'
+
+type TiptapHtmlServer = typeof import('@tiptap/html/server')
+
+const requireFromHere = createRequire(import.meta.url)
+let tiptapHtmlServer: TiptapHtmlServer | null = null
+
+function getTiptapHtmlServer(): TiptapHtmlServer {
+  if (!tiptapHtmlServer) {
+    tiptapHtmlServer = requireFromHere('@tiptap/html/server') as TiptapHtmlServer
+  }
+  return tiptapHtmlServer
+}
+
+function hasRenderableContent(node: JSONContent): boolean {
+  if (node.type === 'text') return Boolean(node.text)
+  if (Array.isArray(node.content) && node.content.some(hasRenderableContent)) return true
+  return Boolean(node.type && node.type !== 'doc' && node.type !== 'paragraph' && node.type !== 'text')
+}
+
+export function yDocToContent(ydoc: Y.Doc): { html: string; text: string } | null {
+  try {
+    if (ydoc.getXmlFragment(COLLAB_FRAGMENT_FIELD).length === 0) {
+      return { html: '', text: '' }
+    }
+
+    const json = TiptapTransformer.fromYdoc(ydoc, COLLAB_FRAGMENT_FIELD) as JSONContent | null
+    if (!json || !hasRenderableContent(json)) {
+      return { html: '', text: '' }
+    }
+
+    const { generateHTML } = getTiptapHtmlServer()
+    const html = generateHTML(json, getDocumentEditorExtensions())
+    const text = deriveContentTextFromHtml(html)
+    assertDocumentContentResourceLimits({ contentHtml: html, contentText: text })
+    return { html, text }
+  } catch (error) {
+    if (isCrudHttpError(error) && error.status === 413) throw error
+    return null
+  }
+}
+
+export function htmlToYDoc(html: string): Y.Doc {
+  assertDocumentContentResourceLimits({ contentHtml: html })
+  if (!html.trim()) return new Y.Doc()
+
+  const extensions = getDocumentEditorExtensions()
+  const { generateJSON } = getTiptapHtmlServer()
+  const json = generateJSON(html, extensions) as JSONContent
+  return TiptapTransformer.toYdoc(json, COLLAB_FRAGMENT_FIELD, extensions)
+}
+
+export type MaterializedDocumentHtml = {
+  yjsState: Buffer
+  html: string
+  text: string
+}
+
+/**
+ * Convert authored HTML through the same editor/Yjs pipeline used by persisted
+ * document content. Callers that preview content before writing it must use the
+ * returned HTML too, otherwise the preview can differ from the canonical markup
+ * users receive after the document is created.
+ */
+export function materializeDocumentHtml(html: string): MaterializedDocumentHtml | null {
+  try {
+    const ydoc = htmlToYDoc(html)
+    const content = yDocToContent(ydoc)
+    if (!content) return null
+    const result = {
+      yjsState: Buffer.from(Y.encodeStateAsUpdate(ydoc)),
+      html: content.html,
+      text: content.text,
+    }
+    assertDocumentContentResourceLimits({
+      yjsState: result.yjsState,
+      contentHtml: result.html,
+      contentText: result.text,
+    })
+    return result
+  } catch (error) {
+    if (isCrudHttpError(error) && error.status === 413) throw error
+    return null
+  }
+}
+
+/**
+ * Replace REST-authored content as a Yjs update derived from the current CRDT
+ * epoch. Keeping the old structs as deleted tombstones means a retained client
+ * can merge the replacement without resurrecting or duplicating stale text.
+ */
+export function materializeDocumentContentReplacement(
+  existingState: Buffer | Uint8Array | null | undefined,
+  html: string,
+): MaterializedDocumentHtml | null {
+  try {
+    assertDocumentContentResourceLimits({ yjsState: existingState, contentHtml: html })
+    const replacement = htmlToYDoc(html)
+    const ydoc = new Y.Doc()
+    if (existingState && existingState.length > 0) {
+      Y.applyUpdate(ydoc, new Uint8Array(existingState))
+    }
+
+    const target = ydoc.getXmlFragment(COLLAB_FRAGMENT_FIELD)
+    const replacementNodes = replacement
+      .getXmlFragment(COLLAB_FRAGMENT_FIELD)
+      .toArray()
+      .filter((node): node is Y.XmlElement | Y.XmlText => (
+        node instanceof Y.XmlElement || node instanceof Y.XmlText
+      ))
+      .map((node) => node.clone())
+    ydoc.transact(() => {
+      if (target.length > 0) target.delete(0, target.length)
+      if (replacementNodes.length > 0) target.insert(0, replacementNodes)
+    })
+    const content = yDocToContent(ydoc)
+    if (!content) return null
+    const result = {
+      yjsState: Buffer.from(Y.encodeStateAsUpdate(ydoc)),
+      html: content.html,
+      text: content.text,
+    }
+    assertDocumentContentResourceLimits({
+      yjsState: result.yjsState,
+      contentHtml: result.html,
+      contentText: result.text,
+    })
+    return result
+  } catch (error) {
+    if (isCrudHttpError(error) && error.status === 413) throw error
+    return null
+  }
+}

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

@@ -0,0 +1,170 @@
+import { signJwt, verifyJwt } from '@open-mercato/shared/lib/auth/jwt'
+import type { DocumentTier } from '../lib/permissions'
+
+export const COLLAB_TOKEN_AUDIENCE = 'documents-collab'
+export const COLLAB_TOKEN_V2_AUDIENCE = 'documents-collab-v2'
+export const COLLAB_TOKEN_TTL_SECONDS = 60
+export const COLLAB_TOKEN_CLOCK_SKEW_SECONDS = 5
+export const COLLAB_TOKEN_V2_MIN_SECRET_BYTES = 32
+
+export type CollabTokenClaims = {
+  userId: string
+  tenantId: string
+  organizationId: string
+  documentId: string
+  tier: DocumentTier
+}
+
+export type CollabTokenV2MintInput = CollabTokenClaims & {
+  tokenVersion: 2
+  readOnly: boolean
+}
+
+export type VerifiedCollabTokenV2Claims = CollabTokenV2MintInput & {
+  exp: number
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+function isDocumentTier(value: unknown): value is DocumentTier {
+  return value === 'owner' || value === 'editor' || value === 'commenter' || value === 'viewer'
+}
+
+function readV2Secret(): string | null {
+  const secret = process.env.DOCUMENTS_COLLAB_JWT_SECRET_V2?.trim()
+  if (!secret || new TextEncoder().encode(secret).byteLength < COLLAB_TOKEN_V2_MIN_SECRET_BYTES) {
+    return null
+  }
+  const explicitV1Secret = process.env.DOCUMENTS_COLLAB_JWT_SECRET?.trim()
+  return explicitV1Secret === secret ? null : secret
+}
+
+export function isCollabTokenV2Ready(): boolean {
+  return readV2Secret() !== null
+}
+
+function requireV2Secret(): string {
+  const secret = readV2Secret()
+  if (!secret) {
+    throw new Error(
+      `[internal] DOCUMENTS_COLLAB_JWT_SECRET_V2 must contain at least ${COLLAB_TOKEN_V2_MIN_SECRET_BYTES} UTF-8 bytes and differ from DOCUMENTS_COLLAB_JWT_SECRET`,
+    )
+  }
+  return secret
+}
+
+function readCommonClaims(claims: Record<string, unknown>): CollabTokenClaims | null {
+  const { userId, tenantId, organizationId, documentId, tier } = claims
+  if (
+    !isNonEmptyString(userId)
+    || !isNonEmptyString(tenantId)
+    || !isNonEmptyString(organizationId)
+    || !isNonEmptyString(documentId)
+    || !isDocumentTier(tier)
+  ) {
+    return null
+  }
+
+  return { userId, tenantId, organizationId, documentId, tier }
+}
+
+export function mintCollabToken(claims: CollabTokenClaims): string {
+  return signJwt(
+    { ...claims, sub: claims.userId },
+    {
+      audience: COLLAB_TOKEN_AUDIENCE,
+      secret: process.env.DOCUMENTS_COLLAB_JWT_SECRET,
+      expiresInSec: COLLAB_TOKEN_TTL_SECONDS,
+    },
+  )
+}
+
+/**
+ * Legacy v1 acceptance is a rollout bridge only. Nothing mints v1 tokens
+ * anymore, so the sidecar accepts them solely while a dedicated
+ * DOCUMENTS_COLLAB_JWT_SECRET is explicitly configured and at least as strong
+ * as the v2 minimum. Default deployments (derived JWT_SECRET fallback) accept
+ * v2 tokens exclusively.
+ */
+export function resolveLegacyCollabTokenVerifier(
+  env: Record<string, string | undefined> = process.env,
+): ((token: string) => CollabTokenClaims | null) | null {
+  const secret = env.DOCUMENTS_COLLAB_JWT_SECRET?.trim()
+  if (!secret || new TextEncoder().encode(secret).byteLength < COLLAB_TOKEN_V2_MIN_SECRET_BYTES) {
+    return null
+  }
+  return verifyCollabToken
+}
+
+export function verifyCollabToken(token: string): CollabTokenClaims | null {
+  let payload: unknown
+  try {
+    payload = verifyJwt(token, {
+      audience: COLLAB_TOKEN_AUDIENCE,
+      secret: process.env.DOCUMENTS_COLLAB_JWT_SECRET,
+    })
+  } catch {
+    return null
+  }
+
+  if (!payload || typeof payload !== 'object') return null
+
+  return readCommonClaims(payload as Record<string, unknown>)
+}
+
+export function mintCollabTokenV2(claims: CollabTokenV2MintInput): string {
+  return signJwt(
+    { ...claims, sub: claims.userId },
+    {
+      audience: COLLAB_TOKEN_V2_AUDIENCE,
+      secret: requireV2Secret(),
+      expiresInSec: COLLAB_TOKEN_TTL_SECONDS,
+    },
+  )
+}
+
+export function verifyCollabTokenV2(token: string): VerifiedCollabTokenV2Claims | null {
+  const secret = readV2Secret()
+  if (!secret) return null
+
+  let payload: unknown
+  try {
+    payload = verifyJwt(token, {
+      audience: COLLAB_TOKEN_V2_AUDIENCE,
+      secret,
+    })
+  } catch {
+    return null
+  }
+  if (!payload || typeof payload !== 'object') return null
+
+  const claims = payload as Record<string, unknown>
+  const common = readCommonClaims(claims)
+  const { exp, iat, readOnly, tokenVersion } = claims
+  const now = Math.floor(Date.now() / 1000)
+  if (
+    !common
+    || tokenVersion !== 2
+    || typeof readOnly !== 'boolean'
+    || typeof exp !== 'number'
+    || !Number.isInteger(exp)
+    || typeof iat !== 'number'
+    || !Number.isInteger(iat)
+    || exp <= now
+    || exp <= iat
+    || exp - iat > COLLAB_TOKEN_TTL_SECONDS
+    || iat > now + COLLAB_TOKEN_CLOCK_SKEW_SECONDS
+    || exp > now + COLLAB_TOKEN_TTL_SECONDS + COLLAB_TOKEN_CLOCK_SKEW_SECONDS
+  ) {
+    return null
+  }
+
+  return {
+    ...common,
+    tokenVersion,
+    readOnly,
+    exp,
+  }
+}

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

@@ -0,0 +1,102 @@
+import { sanitizeDocumentsDisplayLabel } from './displayLabels'
+
+export const COLLABORATION_COLOR_FALLBACK = '#64748b'
+
+const COLLABORATION_COLOR_PATTERN = /^#[0-9a-f]{6}$/i
+const UNSAFE_AWARENESS_NAME_PATTERN =
+  /[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u202a-\u202e\u2060-\u2069\ufeff]/u
+const MAX_AWARENESS_NAME_LENGTH = 120
+
+function isEncryptedAwarenessName(value: string): boolean {
+  const parts = value.split(':')
+  return parts.length === 4 && parts[3] === 'v1'
+}
+
+function hashString(value: string): number {
+  let hash = 2166136261
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index)
+    hash = Math.imul(hash, 16777619)
+  }
+  return hash >>> 0
+}
+
+function channelToHex(value: number): string {
+  return Math.round(value).toString(16).padStart(2, '0')
+}
+
+function hslToHex(hue: number, saturationPercent: number, lightnessPercent: number): string {
+  const saturation = saturationPercent / 100
+  const lightness = lightnessPercent / 100
+  const chroma = (1 - Math.abs(2 * lightness - 1)) * saturation
+  const intermediate = chroma * (1 - Math.abs(((hue / 60) % 2) - 1))
+  const match = lightness - chroma / 2
+  const [red, green, blue] =
+    hue < 60 ? [chroma, intermediate, 0]
+      : hue < 120 ? [intermediate, chroma, 0]
+        : hue < 180 ? [0, chroma, intermediate]
+          : hue < 240 ? [0, intermediate, chroma]
+            : hue < 300 ? [intermediate, 0, chroma]
+              : [chroma, 0, intermediate]
+  return `#${channelToHex((red + match) * 255)}${channelToHex((green + match) * 255)}${channelToHex((blue + match) * 255)}`
+}
+
+/**
+ * Awareness colors are interpolated into inline styles by TipTap. Accept only
+ * the single canonical representation emitted by the server, never general
+ * CSS color syntax.
+ */
+export function normalizeCollaborationColor(value: unknown): string {
+  if (typeof value !== 'string' || !COLLABORATION_COLOR_PATTERN.test(value)) {
+    return COLLABORATION_COLOR_FALLBACK
+  }
+  return value.toLowerCase()
+}
+
+export function resolveCollaborationUserColor(userId: string): string {
+  return hslToHex(hashString(userId) % 360, 64, 42)
+}
+
+/**
+ * Presence names come from an authenticated profile, but still cross the Yjs
+ * awareness boundary. Reject control, directionality, zero-width and UUID
+ * content and encryption envelopes so a collaborator cannot visually
+ * impersonate another identity or leak internal data through a caret label.
+ */
+export function sanitizeCollaborationAwarenessName(value: unknown): string {
+  const label = sanitizeDocumentsDisplayLabel(value)
+  if (
+    !label
+    || label.length > MAX_AWARENESS_NAME_LENGTH
+    || UNSAFE_AWARENESS_NAME_PATTERN.test(label)
+    || isEncryptedAwarenessName(label)
+  ) {
+    return ''
+  }
+  return label
+}
+
+export function firstSafeCollaborationAwarenessName(...values: unknown[]): string {
+  for (const value of values) {
+    const label = sanitizeCollaborationAwarenessName(value)
+    if (label) return label
+  }
+  return ''
+}
+
+export type CanonicalCollaborationAwarenessUser = {
+  id: string
+  name: string
+  color: string
+}
+
+export function createCanonicalCollaborationAwarenessUser(
+  userId: string,
+  name: unknown,
+): CanonicalCollaborationAwarenessUser {
+  return {
+    id: userId,
+    name: sanitizeCollaborationAwarenessName(name),
+    color: resolveCollaborationUserColor(userId),
+  }
+}

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

@@ -0,0 +1,19 @@
+import {
+  documentCommentAnchorWriteSchema,
+  type DocumentCommentAnchor,
+} from '../data/validators'
+
+export type NormalizedDocumentCommentAnchor =
+  | DocumentCommentAnchor
+  | { kind: 'legacy-unknown' }
+
+export function normalizeDocumentCommentAnchor(value: unknown): NormalizedDocumentCommentAnchor {
+  const parsed = documentCommentAnchorWriteSchema.safeParse(value)
+  return parsed.success ? parsed.data : { kind: 'legacy-unknown' }
+}
+
+export function isChangedDocumentCommentAnchor(
+  value: NormalizedDocumentCommentAnchor,
+): value is { kind: 'legacy-unknown' } {
+  return 'kind' in value && value.kind === 'legacy-unknown'
+}

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

@@ -0,0 +1,39 @@
+export const DOCUMENTS_ENTITY_IDS = {
+  document: 'documents:document',
+  documentContent: 'documents:document_content',
+  documentFolder: 'documents:document_folder',
+  documentShare: 'documents:document_share',
+  documentComment: 'documents:document_comment',
+  documentFavorite: 'documents:document_favorite',
+  documentWatcher: 'documents:document_watcher',
+  documentVersion: 'documents:document_version',
+  documentAttachment: 'documents:document_attachment',
+  documentTemplate: 'documents:document_template',
+  documentEntityLink: 'documents:document_entity_link',
+} as const
+
+/** Maximum number of folder nodes from a root through its deepest descendant. */
+export const DOCUMENTS_MAX_FOLDER_DEPTH = 64
+
+/**
+ * Maximum active folders one organization may hold. A navigable folder tree
+ * stays in the tens or low hundreds, so this only stops runaway automated
+ * creation while bounding the manager-override listing that decrypts every
+ * folder in scope.
+ */
+export const DOCUMENTS_MAX_FOLDERS_PER_ORGANIZATION = 2_000
+
+/**
+ * Upper bound for one manager-override folder listing. Kept far above the
+ * creation cap so an organization that predates that cap still lists a
+ * coherent tree it can prune, instead of losing folder navigation entirely.
+ */
+export const DOCUMENTS_MAX_LISTED_FOLDERS = 5_000
+
+/**
+ * Upper bound for one document's share listing. Explicit sharing stays in the
+ * tens, and the mention path can only add one share per distinct mentioned
+ * user, so this sits at the comment cap and keeps the listing (plus its
+ * principal-label fan-out) bounded the way the comment and version lists are.
+ */
+export const DOCUMENTS_MAX_LISTED_SHARES = 500