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

package/src/index.ts

@@ -0,0 +1 @@
+export { metadata } from './modules/documents/index'

package/src/modules/documents/acl.ts

@@ -0,0 +1,11 @@
+export const features = [
+  { id: 'documents.view', title: 'View documents', module: 'documents' },
+  { id: 'documents.create', title: 'Create documents', module: 'documents', dependsOn: ['documents.view'] },
+  { id: 'documents.edit', title: 'Edit documents', module: 'documents', dependsOn: ['documents.view'] },
+  { id: 'documents.delete', title: 'Delete documents', module: 'documents', dependsOn: ['documents.view'] },
+  { id: 'documents.share', title: 'Share documents', module: 'documents', dependsOn: ['documents.view'] },
+  { id: 'documents.templates.manage', title: 'Manage document templates', module: 'documents', dependsOn: ['documents.view'] },
+  { id: 'documents.manage', title: 'Manage all documents', module: 'documents', dependsOn: ['documents.view'] },
+]
+
+export default features

package/src/modules/documents/api/[id]/archive/route.ts

@@ -0,0 +1,132 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { enforceCommandOptimisticLockWithGuards } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { Document } from '../../../data/entities'
+import { DOCUMENTS_ENTITY_IDS } from '../../../lib/constants'
+import type { DocumentLifecycleCommandInput, DocumentLifecycleCommandResult } from '../../../commands/lifecycle'
+import {
+  attachDocumentsOperationMetadata,
+  buildDocumentsCommandRuntimeContext,
+  resolveDocumentsCommandBus,
+} from '../../_commands'
+import {
+  handleDocumentsRouteError,
+  resolveActorUserId,
+  resolveDocumentCapabilityProjection,
+  resolveDocumentsContext,
+  routeErrorSchema,
+  runMutationGuardAfterSuccess,
+  validateMutationGuard,
+  withDocumentsContextErrors,
+} from '../../_shared'
+
+type RouteContext = {
+  params: Promise<{ id: string }> | { id: string }
+}
+
+const lifecycleResponseSchema = z.object({
+  id: z.string().uuid(),
+  archivedAt: z.string().nullable(),
+  updatedAt: z.string(),
+})
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['documents.edit'] },
+}
+
+export async function runDocumentLifecycleRoute(
+  request: Request,
+  context: RouteContext,
+  commandId: 'documents.document.archive' | 'documents.document.unarchive',
+  errorScope: string,
+): Promise<Response> {
+  try {
+    const { id: documentId } = await context.params
+    const ctx = await resolveDocumentsContext(request, ['documents.edit'])
+    const projection = await resolveDocumentCapabilityProjection(ctx, documentId)
+    if (!projection.capabilities.canArchive) throw new CrudHttpError(403, { error: 'Forbidden' })
+
+    const document = await findOneWithDecryption(
+      ctx.em,
+      Document,
+      {
+        id: documentId,
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId,
+        deletedAt: null,
+      },
+      { fields: ['id', 'archivedAt', 'updatedAt'] },
+      { tenantId: ctx.tenantId, organizationId: ctx.organizationId },
+    )
+    if (!document) throw new CrudHttpError(404, { error: 'documents.documents.notFound' })
+    await enforceCommandOptimisticLockWithGuards(ctx.container, {
+      resourceKind: DOCUMENTS_ENTITY_IDS.document,
+      resourceId: documentId,
+      current: document.updatedAt,
+      request,
+    })
+
+    const guardResult = await validateMutationGuard(ctx, {
+      resourceKind: DOCUMENTS_ENTITY_IDS.document,
+      resourceId: documentId,
+      operation: 'update',
+      mutationPayload: { action: commandId === 'documents.document.archive' ? 'archive' : 'unarchive' },
+    })
+
+    const input: DocumentLifecycleCommandInput = {
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      documentId,
+      actorUserId: resolveActorUserId(ctx.auth),
+      expectedUpdatedAt: document.updatedAt.toISOString(),
+    }
+    const execution = await resolveDocumentsCommandBus(ctx).execute<
+      DocumentLifecycleCommandInput,
+      DocumentLifecycleCommandResult
+    >(commandId, { input, ctx: buildDocumentsCommandRuntimeContext(ctx) })
+
+    await runMutationGuardAfterSuccess(ctx, guardResult, {
+      resourceKind: DOCUMENTS_ENTITY_IDS.document,
+      resourceId: documentId,
+      operation: 'update',
+    })
+    return attachDocumentsOperationMetadata(
+      NextResponse.json({
+        id: execution.result.id,
+        archivedAt: execution.result.archivedAt,
+        updatedAt: execution.result.updatedAt,
+      }),
+      execution.logEntry,
+      { resourceKind: DOCUMENTS_ENTITY_IDS.document, resourceId: documentId },
+    )
+  } catch (error) {
+    return handleDocumentsRouteError(error, errorScope)
+  }
+}
+
+export async function POST(request: Request, context: RouteContext): Promise<Response> {
+  return runDocumentLifecycleRoute(request, context, 'documents.document.archive', 'documents.archive')
+}
+
+export const openApi: OpenApiRouteDoc = withDocumentsContextErrors({
+  tag: 'Documents',
+  summary: 'Archive document',
+  pathParams: z.object({ id: z.string().uuid() }),
+  methods: {
+    POST: {
+      summary: 'Archive a document, making it read-only and hidden from default listings',
+      responses: [{ status: 200, description: 'Archived document state', schema: lifecycleResponseSchema }],
+      errors: [
+        { status: 401, description: 'Unauthorized', schema: routeErrorSchema },
+        { status: 403, description: 'Forbidden', schema: routeErrorSchema },
+        { status: 404, description: 'Document not found', schema: routeErrorSchema },
+        { status: 409, description: 'Document changed concurrently', schema: routeErrorSchema },
+      ],
+    },
+  },
+})
+
+export default { POST }

package/src/modules/documents/api/[id]/attachments/[attachmentId]/route.ts

@@ -0,0 +1,166 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { DocumentAttachment } from '../../../../data/entities'
+import { DOCUMENTS_ENTITY_IDS } from '../../../../lib/constants'
+import { resolveAttachmentServicePort } from '../../../../lib/attachmentServicePort'
+import { assertTier } from '../../../../lib/permissions'
+import {
+  assertDocumentNotArchived,
+  handleDocumentsRouteError,
+  resolveDocumentsContext,
+  routeErrorSchema,
+  runMutationGuardAfterSuccess,
+  validateMutationGuard,
+  withDocumentsContextErrors,
+} from '../../../_shared'
+import {
+  buildDocumentsCommandRuntimeContext,
+  resolveDocumentsCommandBus,
+} from '../../../_commands'
+import type { DocumentAttachmentDeleteCommandInput } from '../../../../commands/attachments'
+
+type RouteContext = {
+  params: Promise<{ id: string; attachmentId: string }> | { id: string; attachmentId: string }
+}
+
+const attachmentBinaryResponseSchema = z.unknown().describe('Binary file content')
+const attachmentDeleteResponseSchema = z.object({ ok: z.boolean() })
+const DOCUMENT_ATTACHMENT_PARTITION_CODE = 'privateAttachments'
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['documents.view'] },
+  DELETE: { requireAuth: true, requireFeatures: ['documents.edit'] },
+}
+
+async function resolveParams(context: RouteContext): Promise<{ documentId: string; attachmentId: string }> {
+  const params = await context.params
+  return { documentId: params.id, attachmentId: params.attachmentId }
+}
+
+async function loadDocumentAttachment(
+  ctx: Awaited<ReturnType<typeof resolveDocumentsContext>>,
+  documentId: string,
+  attachmentId: string,
+): Promise<DocumentAttachment> {
+  const documentAttachment = await findOneWithDecryption(
+    ctx.em,
+    DocumentAttachment,
+    {
+      documentId,
+      attachmentId,
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      deletedAt: null,
+    },
+    undefined,
+    { tenantId: ctx.tenantId, organizationId: ctx.organizationId },
+  )
+  if (!documentAttachment) throw new CrudHttpError(404, { error: 'Attachment not found' })
+  return documentAttachment
+}
+
+export async function GET(request: Request, context: RouteContext): Promise<Response> {
+  try {
+    const { documentId, attachmentId } = await resolveParams(context)
+    const ctx = await resolveDocumentsContext(request, ['documents.view'])
+    await assertTier(ctx.em, documentId, ctx.auth, 'viewer')
+    await loadDocumentAttachment(ctx, documentId, attachmentId)
+    const forceDownload = new URL(request.url).searchParams.get('download') === '1'
+    const attachmentService = resolveAttachmentServicePort(ctx.container)
+    const result = await attachmentService.readScoped({
+      attachmentId,
+      auth: ctx.auth,
+      expectedOwner: { entityId: DOCUMENTS_ENTITY_IDS.document, recordId: documentId },
+      expectedAssignment: { type: DOCUMENTS_ENTITY_IDS.document, id: documentId },
+      expectedPartitionCode: DOCUMENT_ATTACHMENT_PARTITION_CODE,
+      requirePrivatePartition: true,
+      forceDownload,
+    })
+    const headers: Record<string, string> = {
+      'Cache-Control': 'private, no-store, max-age=0, must-revalidate',
+      'Content-Security-Policy': "default-src 'none'; sandbox",
+      'Content-Type': result.contentType,
+      'Content-Disposition': result.contentDisposition,
+      'Content-Length': String(result.buffer.length),
+      'Expires': '0',
+      'Pragma': 'no-cache',
+      'X-Content-Type-Options': 'nosniff',
+    }
+
+    return new NextResponse(new Uint8Array(result.buffer), { status: 200, headers })
+  } catch (error) {
+    return handleDocumentsRouteError(error, 'documents.attachments.read')
+  }
+}
+
+export async function DELETE(request: Request, context: RouteContext): Promise<Response> {
+  try {
+    const { documentId, attachmentId } = await resolveParams(context)
+    const ctx = await resolveDocumentsContext(request, ['documents.edit'])
+    await assertTier(ctx.em, documentId, ctx.auth, 'editor')
+    await assertDocumentNotArchived(ctx, documentId)
+    const documentAttachment = await loadDocumentAttachment(ctx, documentId, attachmentId)
+    const guardResult = await validateMutationGuard(ctx, {
+      resourceKind: DOCUMENTS_ENTITY_IDS.documentAttachment,
+      resourceId: documentAttachment.id,
+      operation: 'delete',
+      mutationPayload: { documentId, attachmentId },
+    })
+    const input: DocumentAttachmentDeleteCommandInput = {
+      documentId,
+      attachmentId,
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+    }
+    await resolveDocumentsCommandBus(ctx).execute('documents.attachment.delete', {
+      input,
+      ctx: buildDocumentsCommandRuntimeContext(ctx),
+    })
+    await runMutationGuardAfterSuccess(ctx, guardResult, {
+      resourceKind: DOCUMENTS_ENTITY_IDS.documentAttachment,
+      resourceId: documentAttachment.id,
+      operation: 'delete',
+    })
+    return NextResponse.json({ ok: true })
+  } catch (error) {
+    return handleDocumentsRouteError(error, 'documents.attachments.delete')
+  }
+}
+
+export const openApi: OpenApiRouteDoc = withDocumentsContextErrors({
+  tag: 'Documents',
+  summary: 'Read document attachment',
+  pathParams: z.object({
+    id: z.string().uuid(),
+    attachmentId: z.string().uuid(),
+  }),
+  methods: {
+    GET: {
+      summary: 'Read a document-scoped attachment',
+      responses: [{ status: 200, description: 'Attachment bytes', schema: attachmentBinaryResponseSchema }],
+      errors: [
+        { status: 401, description: 'Unauthorized', schema: routeErrorSchema },
+        { status: 403, description: 'Forbidden', schema: routeErrorSchema },
+        { status: 404, description: 'Attachment not found', schema: routeErrorSchema },
+        { status: 500, description: 'Partition misconfigured', schema: routeErrorSchema },
+        { status: 503, description: 'Attachment service unavailable', schema: routeErrorSchema },
+      ],
+    },
+    DELETE: {
+      summary: 'Detach a document-scoped attachment',
+      description: 'Transactionally removes the document attachment row and quota usage, then runs reference-checked provider cleanup after commit. This operation is audited and intentionally not undoable.',
+      responses: [{ status: 200, description: 'Attachment deletion committed', schema: attachmentDeleteResponseSchema }],
+      errors: [
+        { status: 401, description: 'Unauthorized', schema: routeErrorSchema },
+        { status: 403, description: 'Forbidden', schema: routeErrorSchema },
+        { status: 404, description: 'Attachment not found', schema: routeErrorSchema },
+        { status: 409, description: 'Optimistic lock conflict or attachment still referenced', schema: routeErrorSchema },
+      ],
+    },
+  },
+})
+
+export default { GET, DELETE }

package/src/modules/documents/api/[id]/attachments/route.ts

@@ -0,0 +1,173 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import {
+  DOCUMENT_ATTACHMENT_UPLOAD_CONTEXT,
+  type DocumentAttachmentCreateCommandInput,
+  type DocumentAttachmentCreateCommandResult,
+} from '../../../commands/attachments'
+import { DOCUMENTS_ENTITY_IDS } from '../../../lib/constants'
+import { readAttachmentUploadForm, resolveAttachmentServicePort } from '../../../lib/attachmentServicePort'
+import { assertTier } from '../../../lib/permissions'
+import {
+  assertDocumentNotArchived,
+  handleDocumentsRouteError,
+  loadScopedDocument,
+  resolveDocumentsContext,
+  routeErrorSchema,
+  runMutationGuardAfterSuccess,
+  validateMutationGuard,
+  withDocumentsContextErrors,
+} from '../../_shared'
+import {
+  attachDocumentsOperationMetadata,
+  buildDocumentsCommandRuntimeContext,
+  resolveDocumentsCommandBus,
+} from '../../_commands'
+
+type RouteContext = {
+  params: Promise<{ id: string }> | { id: string }
+}
+
+const attachmentUploadBodySchema = z.object({
+  file: z.string().min(1).describe('Binary file payload supplied as multipart form-data'),
+})
+
+// The guard sees exactly the fields the command consumes. `fileSize` is pinned
+// to the real byte length: a guard may rename or retype a file, but it must not
+// be able to talk the route past the upload-size validation below.
+const attachmentGuardPayloadSchema = z.object({
+  fileName: z.string().trim().min(1),
+  fileType: z.string(),
+  fileSize: z.number().int().nonnegative(),
+})
+
+const attachmentUploadResponseSchema = z.object({
+  id: z.string().uuid(),
+  attachmentId: z.string().uuid(),
+  updatedAt: z.string().datetime(),
+  url: z.string(),
+})
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['documents.edit'] },
+}
+
+async function resolveId(context: RouteContext): Promise<string> {
+  const params = await context.params
+  return params.id
+}
+
+function assertMultipartUpload(request: Request): void {
+  const contentType = request.headers.get('content-type') ?? ''
+  if (!contentType.toLowerCase().includes('multipart/form-data')) {
+    throw new CrudHttpError(400, { error: 'Expected multipart/form-data' })
+  }
+}
+
+function readUploadFile(form: FormData): File {
+  const file = form.get('file')
+  if (!(file instanceof File)) {
+    throw new CrudHttpError(400, { error: 'File is required' })
+  }
+  return file
+}
+
+export async function POST(request: Request, context: RouteContext): Promise<Response> {
+  try {
+    const documentId = await resolveId(context)
+    const ctx = await resolveDocumentsContext(request, ['documents.edit'])
+    await assertTier(ctx.em, documentId, ctx.auth, 'editor')
+    await assertDocumentNotArchived(ctx, documentId)
+    await loadScopedDocument(ctx, documentId)
+    const attachmentService = resolveAttachmentServicePort(ctx.container)
+    assertMultipartUpload(request)
+    const form = await readAttachmentUploadForm(attachmentService, request)
+    const file = readUploadFile(form)
+    attachmentService.validateUpload({ fileName: file.name, fileSize: file.size })
+    const guardPayload = attachmentGuardPayloadSchema.parse({
+      fileName: file.name,
+      fileType: file.type,
+      fileSize: file.size,
+    })
+    const guardResult = await validateMutationGuard(ctx, {
+      resourceKind: DOCUMENTS_ENTITY_IDS.documentAttachment,
+      resourceId: documentId,
+      operation: 'create',
+      mutationPayload: guardPayload,
+      mutationPayloadSchema: attachmentGuardPayloadSchema.refine(
+        (payload) => payload.fileSize === file.size,
+        { path: ['fileSize'], message: '[internal] mutation guard changed the file size' },
+      ),
+    })
+    // Re-validate against the possibly rewritten name before the bytes are read.
+    attachmentService.validateUpload({
+      fileName: guardPayload.fileName,
+      fileSize: guardPayload.fileSize,
+    })
+
+    const buffer = Buffer.from(await file.arrayBuffer())
+    const commandInput: DocumentAttachmentCreateCommandInput = {
+      documentId,
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      fileName: guardPayload.fileName,
+      fileType: guardPayload.fileType || null,
+      fileSize: guardPayload.fileSize,
+    }
+    const commandContext = {
+      ...buildDocumentsCommandRuntimeContext(ctx),
+      [DOCUMENT_ATTACHMENT_UPLOAD_CONTEXT]: { buffer },
+    }
+    const { result, logEntry } = await resolveDocumentsCommandBus(ctx).execute<
+      DocumentAttachmentCreateCommandInput,
+      DocumentAttachmentCreateCommandResult
+    >('documents.attachment.create', {
+      input: commandInput,
+      ctx: commandContext,
+    })
+
+    await runMutationGuardAfterSuccess(ctx, guardResult, {
+      resourceKind: DOCUMENTS_ENTITY_IDS.documentAttachment,
+      resourceId: result.linkId,
+      operation: 'create',
+    })
+
+    const url = `/api/documents/${encodeURIComponent(documentId)}/attachments/${encodeURIComponent(result.attachmentId)}`
+    const response = NextResponse.json({
+      id: result.id,
+      attachmentId: result.attachmentId,
+      updatedAt: result.updatedAt,
+      url,
+    }, { status: 201 })
+    return attachDocumentsOperationMetadata(response, logEntry, {
+      resourceKind: DOCUMENTS_ENTITY_IDS.documentAttachment,
+      resourceId: result.linkId,
+    })
+  } catch (error) {
+    return handleDocumentsRouteError(error, 'documents.attachments.create')
+  }
+}
+
+export const openApi: OpenApiRouteDoc = withDocumentsContextErrors({
+  tag: 'Documents',
+  summary: 'Document attachments',
+  pathParams: z.object({ id: z.string().uuid() }),
+  methods: {
+    POST: {
+      summary: 'Upload document attachment',
+      requestBody: { contentType: 'multipart/form-data', schema: attachmentUploadBodySchema },
+      responses: [{ status: 201, description: 'Document-scoped attachment uploaded', schema: attachmentUploadResponseSchema }],
+      errors: [
+        { status: 400, description: 'Payload validation error', schema: routeErrorSchema },
+        { status: 401, description: 'Unauthorized', schema: routeErrorSchema },
+        { status: 403, description: 'Forbidden', schema: routeErrorSchema },
+        { status: 413, description: 'Attachment too large', schema: routeErrorSchema },
+        { status: 503, description: 'Attachment service unavailable', schema: routeErrorSchema },
+      ],
+    },
+  },
+})
+
+export default { POST }

package/src/modules/documents/api/[id]/collab-token/route.ts

@@ -0,0 +1,203 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import {
+  COLLAB_TOKEN_TTL_SECONDS,
+  isCollabTokenV2Ready,
+  mintCollabTokenV2,
+  verifyCollabTokenV2,
+} from '../../../lib/collabToken'
+import { resolveUserLabels } from '../../../lib/userLabels'
+import { resolveCollaborationUserColor } from '../../../lib/collaborationAwareness'
+import { resolveDocumentsCollaborationEndpoint } from '../../../lib/collabEndpoint'
+import { resolvePermission } from '../../../lib/permissions'
+import {
+  loadDocumentArchivedState,
+  deriveCapabilitiesForContext,
+  handleDocumentsRouteError,
+  resolveActorUserId,
+  resolveDocumentsContext,
+  routeErrorSchema,
+  withDocumentsContextErrors,
+} from '../../_shared'
+
+type RouteContext = {
+  params: Promise<{ id: string }> | { id: string }
+}
+
+const collabTokenResponseSchema = z.object({
+  token: z.string(),
+  url: z.string().nullable(),
+  documentId: z.string(),
+  tier: z.enum(['owner', 'editor', 'commenter', 'viewer']),
+  expiresInSec: z.number(),
+  expiresAt: z.string(),
+  userName: z.string(),
+  userColor: z.string(),
+  canEdit: z.boolean(),
+  readOnly: z.boolean(),
+  user: z.object({
+    id: z.string(),
+    name: z.string(),
+    color: z.string(),
+  }),
+})
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['documents.view'] },
+}
+
+const logger = createLogger('documents').child({ component: 'api' })
+
+let warnedCollabTokenSecretNotReady = false
+let warnedCollabEndpointInvalid = false
+
+function warnCollabTokenSecretNotReadyOnce(): void {
+  if (warnedCollabTokenSecretNotReady) return
+  warnedCollabTokenSecretNotReady = true
+  logger.warn(
+    'DOCUMENTS_COLLAB_JWT_SECRET_V2 is missing, shorter than 32 UTF-8 bytes, '
+    + 'or equal to DOCUMENTS_COLLAB_JWT_SECRET; collaboration tokens cannot be minted '
+    + 'and clients fall back to non-collaborative editing.',
+  )
+}
+
+function warnCollabEndpointInvalidOnce(): void {
+  if (warnedCollabEndpointInvalid) return
+  warnedCollabEndpointInvalid = true
+  logger.warn(
+    'Ignoring NEXT_PUBLIC_DOCUMENTS_COLLAB_URL because it is not a valid browser-reachable '
+    + 'ws(s) endpoint; collaboration is disabled and clients fall back to non-collaborative editing.',
+  )
+}
+
+export async function GET(request: Request, context: RouteContext): Promise<Response> {
+  try {
+    const params = await context.params
+    const id = params.id
+    const ctx = await resolveDocumentsContext(request, ['documents.view'])
+    // The collaboration sidecar currently reauthorizes the signed user
+    // identity and has no API-key subject with which to reload the key's
+    // restricted ACL/roles. Do not mint a token that would silently promote a
+    // bound key to its backing user's full collaboration access.
+    if (ctx.auth.isApiKey === true || ctx.auth.sub.startsWith('api_key:')) {
+      throw new CrudHttpError(403, { error: 'Forbidden' })
+    }
+    // One relationship lookup feeds both projections. The pre-archive check
+    // still runs first so an unauthorized caller cannot tell an existing
+    // document apart from a missing one via the 404 the archived read raises.
+    const relationshipTier = await resolvePermission(ctx.em, id, ctx.auth)
+    if (!relationshipTier || !deriveCapabilitiesForContext(ctx, relationshipTier).canView) {
+      throw new CrudHttpError(403, { error: 'Forbidden' })
+    }
+    const archivedState = await loadDocumentArchivedState(ctx, id)
+    const capabilities = deriveCapabilitiesForContext(ctx, relationshipTier, {
+      archived: archivedState.archivedAt !== null,
+    })
+    if (!capabilities.canView) {
+      throw new CrudHttpError(403, { error: 'Forbidden' })
+    }
+    const userId = resolveActorUserId(ctx.auth)
+    const [userLabels, translations] = await Promise.all([
+      resolveUserLabels(
+        ctx.container,
+        { tenantId: ctx.tenantId, organizationId: ctx.organizationId },
+        [userId],
+      ),
+      resolveTranslations(),
+    ])
+    const userName = userLabels.get(userId)?.label
+      ?? translations.translate('documents.users.unknown', 'Unknown user')
+    const userColor = resolveCollaborationUserColor(userId)
+    const readOnly = !capabilities.canEdit
+    if (!isCollabTokenV2Ready()) {
+      // A misconfigured capability secret must degrade to the same graceful
+      // non-collaborative response as an unset NEXT_PUBLIC_DOCUMENTS_COLLAB_URL
+      // (url: null) instead of a 500 the client would classify as transient
+      // and retry until its fallback timer.
+      warnCollabTokenSecretNotReadyOnce()
+      return NextResponse.json(
+        {
+          token: '',
+          url: null,
+          documentId: id,
+          tier: relationshipTier,
+          expiresInSec: COLLAB_TOKEN_TTL_SECONDS,
+          expiresAt: new Date(Date.now() + COLLAB_TOKEN_TTL_SECONDS * 1000).toISOString(),
+          userName,
+          userColor,
+          canEdit: capabilities.canEdit,
+          readOnly,
+          user: {
+            id: userId,
+            name: userName,
+            color: userColor,
+          },
+        },
+        { headers: { 'Cache-Control': 'private, no-store' } },
+      )
+    }
+    const collaborationEndpoint = resolveDocumentsCollaborationEndpoint()
+    if (process.env.NEXT_PUBLIC_DOCUMENTS_COLLAB_URL && !collaborationEndpoint) {
+      warnCollabEndpointInvalidOnce()
+    }
+    const token = mintCollabTokenV2({
+      userId,
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      documentId: id,
+      tier: relationshipTier,
+      tokenVersion: 2,
+      readOnly,
+    })
+    const verifiedToken = verifyCollabTokenV2(token)
+    if (!verifiedToken) {
+      throw new Error('[internal] Failed to verify a freshly minted collaboration token')
+    }
+
+    return NextResponse.json(
+      {
+        token,
+        url: collaborationEndpoint,
+        documentId: id,
+        tier: relationshipTier,
+        expiresInSec: COLLAB_TOKEN_TTL_SECONDS,
+        expiresAt: new Date(verifiedToken.exp * 1000).toISOString(),
+        userName,
+        userColor,
+        canEdit: capabilities.canEdit,
+        readOnly,
+        user: {
+          id: userId,
+          name: userName,
+          color: userColor,
+        },
+      },
+      { headers: { 'Cache-Control': 'private, no-store' } },
+    )
+  } catch (error) {
+    return handleDocumentsRouteError(error, 'documents.collabToken.get')
+  }
+}
+
+export const openApi: OpenApiRouteDoc = withDocumentsContextErrors({
+  tag: 'Documents',
+  summary: 'Document collaboration token',
+  pathParams: z.object({ id: z.string().uuid() }),
+  methods: {
+    GET: {
+      summary: 'Mint document collaboration token',
+      responses: [{ status: 200, description: 'Collaboration token', schema: collabTokenResponseSchema }],
+      errors: [
+        { status: 401, description: 'Unauthorized', schema: routeErrorSchema },
+        { status: 403, description: 'Forbidden', schema: routeErrorSchema },
+        { status: 404, description: 'Not found', schema: routeErrorSchema },
+      ],
+    },
+  },
+})
+
+export default { GET }