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

package/README.md

@@ -0,0 +1,88 @@
+# @open-mercato/documents
+
+Collaborative internal documents for Open Mercato: a tenant/organization-scoped backoffice module where staff co-author rich-text documents in real time (TipTap + Yjs), organized in folders, shared per-document (owner / editor / commenter / viewer), annotated with inline comments + @mentions, versioned, and exported to `.docx`/PDF.
+
+Spec: [Documents collaborative editor](../../.ai/specs/2026-07-08-documents-collaborative-editor.md).
+
+## Realtime collaboration sidecar (M2)
+
+Real-time editing is served by a **Hocuspocus WebSocket sidecar** — a separate long-lived Node process, **not** a Next.js route (App Router route handlers can't hold long-lived sockets). Entry: [`server/documents-collab-server.ts`](server/documents-collab-server.ts).
+
+### Run it
+
+```bash
+# Dev (from the repo root, alongside `yarn dev`):
+yarn workspace @open-mercato/documents collab        # tsx server/documents-collab-server.ts
+
+# Production package entry:
+yarn workspace @open-mercato/documents build
+yarn workspace @open-mercato/documents collab:prod
+
+# Scaffolded standalone app (run as a second workload from the same image):
+yarn documents:collab
+```
+
+The sidecar bootstraps the app's module registry + ORM via `bootstrapFromAppRoot()` (the same path the `mercato queue worker` fleet uses), then opens a fresh request-scoped container per document load/store so every query is tenant/org-scoped.
+
+The create-app Docker Compose templates include a `documents-collab` service on port 4101. In other schedulers, run `yarn documents:collab` as a separate service and set `NEXT_PUBLIC_DOCUMENTS_COLLAB_URL` before building the app to its browser-reachable `ws://` or `wss://` endpoint.
+
+### Environment
+
+| Var | Where | Default | Purpose |
+|---|---|---|---|
+| `DOCUMENTS_COLLAB_PORT` | sidecar | `4101` | WebSocket listen port |
+| `DOCUMENTS_COLLAB_REDIS_URL` | sidecar | unset (or `REDIS_URL`) | Redis used to synchronize Yjs updates and awareness across sidecar replicas. When neither is set the sidecar runs single-node mode and logs a startup warning; multi-instance deployments require Redis |
+| `DOCUMENTS_COLLAB_REDIS_PREFIX` | sidecar | development-only local namespace | Deployment-scoped Redis key prefix. Required whenever Redis is configured in production. All replicas in one deployment must share it; deployments using the same Redis database must use different values |
+| `NEXT_PUBLIC_DOCUMENTS_COLLAB_URL` | app (client) | — | `ws(s)://…` the browser connects to; when unset, users with edit capability get optimistic-locked single-user autosave while read-only users keep the last-saved view |
+| `DOCUMENTS_COLLAB_ALLOWED_ORIGINS` | sidecar | local/test: all | comma-separated exact browser origins allowed during the WebSocket handshake. In production the sidecar requires an allowed origin, sourced from this var **or** `APP_URL`/`NEXT_PUBLIC_APP_URL` |
+| `DOCUMENTS_COLLAB_JWT_SECRET_V2` | app + sidecar | unset (fails closed) | shared secret for v2 capability tokens; must contain at least 32 UTF-8 bytes. When unset the app mints no token and clients fall back to non-collaborative editing |
+| `DOCUMENTS_COLLAB_JWT_SECRET` | app + sidecar | — | optional v1 rollout secret; the sidecar accepts legacy v1 tokens **only** while this is set to a ≥32-byte value that differs from the v2 secret |
+| `DOCUMENTS_COLLAB_APP_ROOT` | sidecar | auto-resolved | app root for `bootstrapFromAppRoot` (defaults to the resolved mercato app) |
+| `DOCUMENTS_COLLAB_START` | sidecar | on | set `off` to import the module without auto-starting the server (used by tests) |
+| `DATABASE_URL` | sidecar | — | required for the cross-process event bridge (force-close on unshare/delete/restore) |
+| `DOCUMENTS_PDF_CHROMIUM_PATH` | app (M4) | auto-probe | Chromium/Chrome executable for PDF export (falls back to `PUPPETEER_EXECUTABLE_PATH` then common system paths) |
+
+### Security model (the sidecar is the chokepoint)
+
+1. The browser never holds the raw httpOnly session token. It calls `GET /api/documents/[id]/collab-token`, which verifies the session server-side, computes the caller's effective per-doc capabilities, and returns a **~60s** v2 token scoped to the actor, tenant, organization, document, tier, and read-only state on a dedicated collaboration audience.
+2. `onAuthenticate` verifies the v2 secret, expiry, audience, room binding, tenant/organization scope, and the browser `Origin`; viewer/commenter connections are read-only and failures deny by default.
+3. Write enforcement is Hocuspocus's native `connection.readOnly` (drops a read-only connection's `syncStep2`/`update` messages while still serving reads/awareness), a fresh authorization check before every writable frame is applied, and an `onStoreDocument` read-only-tier early-return.
+4. `onLoadDocument`/`onStoreDocument` open a **fresh request-scoped container per operation** and scope every `DocumentContentService` query by the token's `{ tenantId, organizationId }`. Persist writes `yjs_state` + materializes `content_html`/`content_text` + reindexes.
+5. `documents.document.deleted` / `.unshared` / `.version.restored` (all `crossProcessBroadcast: true`, not browser `clientBroadcast` events) reach the sidecar over the cross-process pg bridge and force-close the affected room; a "closing" flag suppresses the room's final store so a restore can't be clobbered.
+
+### Degrade
+
+If the sidecar is unreachable (or `NEXT_PUBLIC_DOCUMENTS_COLLAB_URL` is unset), a user who still has edit capability gets an **editable single-user fallback**. It persists through the bounded content `PUT` path with the content row's optimistic-lock token, exposes explicit save status/control, and guards navigation while a save is pending. A definitive collaboration authorization rejection, revoked capability, viewer, or commenter remains read-only and fail-closed. PostgreSQL remains authoritative in both modes.
+
+Redis replication is transport-only: the authenticated source replica owns
+persistence and publishes its exact Yjs state only after that store succeeds.
+A dedicated command-bounded publisher releases the store lock before fanout;
+if Redis never acknowledges the release, the sidecar resumes after the lock's
+expiry instead of retaining Hocuspocus' save mutex indefinitely. Redis
+delivery failures retain and retry only the latest durable state for each room,
+so post-store Redis recovery never blocks later PostgreSQL persistence. Each
+durable frame carries the content collaboration generation, and replicas reject
+pre-restore frames before they can merge stale Yjs structs into a replacement room.
+The `OMDF1` generation envelope predates the module's first release. Any future
+wire-version change must use a coordinated, non-overlapping sidecar rollout
+(drain and restart every replica); mixed wire versions are intentionally rejected.
+A receiving replica validates the complete merged state before applying or
+broadcasting it and never competes for the durable store lock with an empty
+authorization context. Receivers subscribe before reading their scoped
+PostgreSQL snapshot and retain the loading Y.Doc until registration, so a
+durable publish racing that read cannot be dropped. Set
+`DOCUMENTS_COLLAB_REDIS_PREFIX` to the same deployment-specific value on every
+replica so collaboration traffic cannot cross application environments that
+share a Redis database.
+
+The real multi-instance regression starts two Hocuspocus servers plus isolated
+Redis and PostgreSQL containers, edits through both replicas, and verifies the
+merged Yjs state in PostgreSQL:
+
+```bash
+yarn workspace @open-mercato/documents test:multi-instance
+```
+
+The main CI workflow runs this command as the required Docker-capable
+`documents-multi-instance` job, independently from the standard Jest suite
+where the test remains skipped by default.

package/build.mjs

@@ -0,0 +1,23 @@
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { buildPackage } from '../../scripts/build-package.mjs'
+
+const packageDir = dirname(fileURLToPath(import.meta.url))
+const watch = process.argv.includes('--watch')
+
+await buildPackage(packageDir, {
+  name: 'documents',
+  clearDist: true,
+  watch,
+})
+
+// The collaboration server is a separate production workload rather than a
+// Next.js route. Compile its public entry so scaffolded apps can run the same
+// package image after development dependencies (including tsx) are pruned.
+await buildPackage(packageDir, {
+  name: 'documents-collab',
+  entryPoints: [join(packageDir, 'server', 'documents-collab-server.ts')],
+  outdir: 'dist',
+  outbase: '.',
+  watch,
+})

package/dist/index.js

@@ -0,0 +1,5 @@
+import { metadata } from "./modules/documents/index.js";
+export {
+  metadata
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["export { metadata } from './modules/documents/index'\n"],
+  "mappings": "AAAA,SAAS,gBAAgB;",
+  "names": []
+}

package/dist/modules/documents/acl.js

@@ -0,0 +1,15 @@
+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"] }
+];
+var acl_default = features;
+export {
+  acl_default as default,
+  features
+};
+//# sourceMappingURL=acl.js.map

package/dist/modules/documents/acl.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/modules/documents/acl.ts"],
+  "sourcesContent": ["export const features = [\n  { id: 'documents.view', title: 'View documents', module: 'documents' },\n  { id: 'documents.create', title: 'Create documents', module: 'documents', dependsOn: ['documents.view'] },\n  { id: 'documents.edit', title: 'Edit documents', module: 'documents', dependsOn: ['documents.view'] },\n  { id: 'documents.delete', title: 'Delete documents', module: 'documents', dependsOn: ['documents.view'] },\n  { id: 'documents.share', title: 'Share documents', module: 'documents', dependsOn: ['documents.view'] },\n  { id: 'documents.templates.manage', title: 'Manage document templates', module: 'documents', dependsOn: ['documents.view'] },\n  { id: 'documents.manage', title: 'Manage all documents', module: 'documents', dependsOn: ['documents.view'] },\n]\n\nexport default features\n"],
+  "mappings": "AAAO,MAAM,WAAW;AAAA,EACtB,EAAE,IAAI,kBAAkB,OAAO,kBAAkB,QAAQ,YAAY;AAAA,EACrE,EAAE,IAAI,oBAAoB,OAAO,oBAAoB,QAAQ,aAAa,WAAW,CAAC,gBAAgB,EAAE;AAAA,EACxG,EAAE,IAAI,kBAAkB,OAAO,kBAAkB,QAAQ,aAAa,WAAW,CAAC,gBAAgB,EAAE;AAAA,EACpG,EAAE,IAAI,oBAAoB,OAAO,oBAAoB,QAAQ,aAAa,WAAW,CAAC,gBAAgB,EAAE;AAAA,EACxG,EAAE,IAAI,mBAAmB,OAAO,mBAAmB,QAAQ,aAAa,WAAW,CAAC,gBAAgB,EAAE;AAAA,EACtG,EAAE,IAAI,8BAA8B,OAAO,6BAA6B,QAAQ,aAAa,WAAW,CAAC,gBAAgB,EAAE;AAAA,EAC3H,EAAE,IAAI,oBAAoB,OAAO,wBAAwB,QAAQ,aAAa,WAAW,CAAC,gBAAgB,EAAE;AAC9G;AAEA,IAAO,cAAQ;",
+  "names": []
+}

package/dist/modules/documents/api/[id]/archive/route.js

@@ -0,0 +1,116 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+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.js";
+import { DOCUMENTS_ENTITY_IDS } from "../../../lib/constants.js";
+import {
+  attachDocumentsOperationMetadata,
+  buildDocumentsCommandRuntimeContext,
+  resolveDocumentsCommandBus
+} from "../../_commands.js";
+import {
+  handleDocumentsRouteError,
+  resolveActorUserId,
+  resolveDocumentCapabilityProjection,
+  resolveDocumentsContext,
+  routeErrorSchema,
+  runMutationGuardAfterSuccess,
+  validateMutationGuard,
+  withDocumentsContextErrors
+} from "../../_shared.js";
+const lifecycleResponseSchema = z.object({
+  id: z.string().uuid(),
+  archivedAt: z.string().nullable(),
+  updatedAt: z.string()
+});
+const metadata = {
+  POST: { requireAuth: true, requireFeatures: ["documents.edit"] }
+};
+async function runDocumentLifecycleRoute(request, context, commandId, errorScope) {
+  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 = {
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      documentId,
+      actorUserId: resolveActorUserId(ctx.auth),
+      expectedUpdatedAt: document.updatedAt.toISOString()
+    };
+    const execution = await resolveDocumentsCommandBus(ctx).execute(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);
+  }
+}
+async function POST(request, context) {
+  return runDocumentLifecycleRoute(request, context, "documents.document.archive", "documents.archive");
+}
+const openApi = 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 }
+      ]
+    }
+  }
+});
+var route_default = { POST };
+export {
+  POST,
+  route_default as default,
+  metadata,
+  openApi,
+  runDocumentLifecycleRoute
+};
+//# sourceMappingURL=route.js.map

package/dist/modules/documents/api/[id]/archive/route.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../src/modules/documents/api/%5Bid%5D/archive/route.ts"],
+  "sourcesContent": ["import { NextResponse } from 'next/server'\nimport { z } from 'zod'\nimport type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'\nimport { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'\nimport { enforceCommandOptimisticLockWithGuards } from '@open-mercato/shared/lib/crud/optimistic-lock-command'\nimport { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'\nimport { Document } from '../../../data/entities'\nimport { DOCUMENTS_ENTITY_IDS } from '../../../lib/constants'\nimport type { DocumentLifecycleCommandInput, DocumentLifecycleCommandResult } from '../../../commands/lifecycle'\nimport {\n  attachDocumentsOperationMetadata,\n  buildDocumentsCommandRuntimeContext,\n  resolveDocumentsCommandBus,\n} from '../../_commands'\nimport {\n  handleDocumentsRouteError,\n  resolveActorUserId,\n  resolveDocumentCapabilityProjection,\n  resolveDocumentsContext,\n  routeErrorSchema,\n  runMutationGuardAfterSuccess,\n  validateMutationGuard,\n  withDocumentsContextErrors,\n} from '../../_shared'\n\ntype RouteContext = {\n  params: Promise<{ id: string }> | { id: string }\n}\n\nconst lifecycleResponseSchema = z.object({\n  id: z.string().uuid(),\n  archivedAt: z.string().nullable(),\n  updatedAt: z.string(),\n})\n\nexport const metadata = {\n  POST: { requireAuth: true, requireFeatures: ['documents.edit'] },\n}\n\nexport async function runDocumentLifecycleRoute(\n  request: Request,\n  context: RouteContext,\n  commandId: 'documents.document.archive' | 'documents.document.unarchive',\n  errorScope: string,\n): Promise<Response> {\n  try {\n    const { id: documentId } = await context.params\n    const ctx = await resolveDocumentsContext(request, ['documents.edit'])\n    const projection = await resolveDocumentCapabilityProjection(ctx, documentId)\n    if (!projection.capabilities.canArchive) throw new CrudHttpError(403, { error: 'Forbidden' })\n\n    const document = await findOneWithDecryption(\n      ctx.em,\n      Document,\n      {\n        id: documentId,\n        tenantId: ctx.tenantId,\n        organizationId: ctx.organizationId,\n        deletedAt: null,\n      },\n      { fields: ['id', 'archivedAt', 'updatedAt'] },\n      { tenantId: ctx.tenantId, organizationId: ctx.organizationId },\n    )\n    if (!document) throw new CrudHttpError(404, { error: 'documents.documents.notFound' })\n    await enforceCommandOptimisticLockWithGuards(ctx.container, {\n      resourceKind: DOCUMENTS_ENTITY_IDS.document,\n      resourceId: documentId,\n      current: document.updatedAt,\n      request,\n    })\n\n    const guardResult = await validateMutationGuard(ctx, {\n      resourceKind: DOCUMENTS_ENTITY_IDS.document,\n      resourceId: documentId,\n      operation: 'update',\n      mutationPayload: { action: commandId === 'documents.document.archive' ? 'archive' : 'unarchive' },\n    })\n\n    const input: DocumentLifecycleCommandInput = {\n      tenantId: ctx.tenantId,\n      organizationId: ctx.organizationId,\n      documentId,\n      actorUserId: resolveActorUserId(ctx.auth),\n      expectedUpdatedAt: document.updatedAt.toISOString(),\n    }\n    const execution = await resolveDocumentsCommandBus(ctx).execute<\n      DocumentLifecycleCommandInput,\n      DocumentLifecycleCommandResult\n    >(commandId, { input, ctx: buildDocumentsCommandRuntimeContext(ctx) })\n\n    await runMutationGuardAfterSuccess(ctx, guardResult, {\n      resourceKind: DOCUMENTS_ENTITY_IDS.document,\n      resourceId: documentId,\n      operation: 'update',\n    })\n    return attachDocumentsOperationMetadata(\n      NextResponse.json({\n        id: execution.result.id,\n        archivedAt: execution.result.archivedAt,\n        updatedAt: execution.result.updatedAt,\n      }),\n      execution.logEntry,\n      { resourceKind: DOCUMENTS_ENTITY_IDS.document, resourceId: documentId },\n    )\n  } catch (error) {\n    return handleDocumentsRouteError(error, errorScope)\n  }\n}\n\nexport async function POST(request: Request, context: RouteContext): Promise<Response> {\n  return runDocumentLifecycleRoute(request, context, 'documents.document.archive', 'documents.archive')\n}\n\nexport const openApi: OpenApiRouteDoc = withDocumentsContextErrors({\n  tag: 'Documents',\n  summary: 'Archive document',\n  pathParams: z.object({ id: z.string().uuid() }),\n  methods: {\n    POST: {\n      summary: 'Archive a document, making it read-only and hidden from default listings',\n      responses: [{ status: 200, description: 'Archived document state', schema: lifecycleResponseSchema }],\n      errors: [\n        { status: 401, description: 'Unauthorized', schema: routeErrorSchema },\n        { status: 403, description: 'Forbidden', schema: routeErrorSchema },\n        { status: 404, description: 'Document not found', schema: routeErrorSchema },\n        { status: 409, description: 'Document changed concurrently', schema: routeErrorSchema },\n      ],\n    },\n  },\n})\n\nexport default { POST }\n"],
+  "mappings": "AAAA,SAAS,oBAAoB;AAC7B,SAAS,SAAS;AAElB,SAAS,qBAAqB;AAC9B,SAAS,8CAA8C;AACvD,SAAS,6BAA6B;AACtC,SAAS,gBAAgB;AACzB,SAAS,4BAA4B;AAErC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAMP,MAAM,0BAA0B,EAAE,OAAO;AAAA,EACvC,IAAI,EAAE,OAAO,EAAE,KAAK;AAAA,EACpB,YAAY,EAAE,OAAO,EAAE,SAAS;AAAA,EAChC,WAAW,EAAE,OAAO;AACtB,CAAC;AAEM,MAAM,WAAW;AAAA,EACtB,MAAM,EAAE,aAAa,MAAM,iBAAiB,CAAC,gBAAgB,EAAE;AACjE;AAEA,eAAsB,0BACpB,SACA,SACA,WACA,YACmB;AACnB,MAAI;AACF,UAAM,EAAE,IAAI,WAAW,IAAI,MAAM,QAAQ;AACzC,UAAM,MAAM,MAAM,wBAAwB,SAAS,CAAC,gBAAgB,CAAC;AACrE,UAAM,aAAa,MAAM,oCAAoC,KAAK,UAAU;AAC5E,QAAI,CAAC,WAAW,aAAa,WAAY,OAAM,IAAI,cAAc,KAAK,EAAE,OAAO,YAAY,CAAC;AAE5F,UAAM,WAAW,MAAM;AAAA,MACrB,IAAI;AAAA,MACJ;AAAA,MACA;AAAA,QACE,IAAI;AAAA,QACJ,UAAU,IAAI;AAAA,QACd,gBAAgB,IAAI;AAAA,QACpB,WAAW;AAAA,MACb;AAAA,MACA,EAAE,QAAQ,CAAC,MAAM,cAAc,WAAW,EAAE;AAAA,MAC5C,EAAE,UAAU,IAAI,UAAU,gBAAgB,IAAI,eAAe;AAAA,IAC/D;AACA,QAAI,CAAC,SAAU,OAAM,IAAI,cAAc,KAAK,EAAE,OAAO,+BAA+B,CAAC;AACrF,UAAM,uCAAuC,IAAI,WAAW;AAAA,MAC1D,cAAc,qBAAqB;AAAA,MACnC,YAAY;AAAA,MACZ,SAAS,SAAS;AAAA,MAClB;AAAA,IACF,CAAC;AAED,UAAM,cAAc,MAAM,sBAAsB,KAAK;AAAA,MACnD,cAAc,qBAAqB;AAAA,MACnC,YAAY;AAAA,MACZ,WAAW;AAAA,MACX,iBAAiB,EAAE,QAAQ,cAAc,+BAA+B,YAAY,YAAY;AAAA,IAClG,CAAC;AAED,UAAM,QAAuC;AAAA,MAC3C,UAAU,IAAI;AAAA,MACd,gBAAgB,IAAI;AAAA,MACpB;AAAA,MACA,aAAa,mBAAmB,IAAI,IAAI;AAAA,MACxC,mBAAmB,SAAS,UAAU,YAAY;AAAA,IACpD;AACA,UAAM,YAAY,MAAM,2BAA2B,GAAG,EAAE,QAGtD,WAAW,EAAE,OAAO,KAAK,oCAAoC,GAAG,EAAE,CAAC;AAErE,UAAM,6BAA6B,KAAK,aAAa;AAAA,MACnD,cAAc,qBAAqB;AAAA,MACnC,YAAY;AAAA,MACZ,WAAW;AAAA,IACb,CAAC;AACD,WAAO;AAAA,MACL,aAAa,KAAK;AAAA,QAChB,IAAI,UAAU,OAAO;AAAA,QACrB,YAAY,UAAU,OAAO;AAAA,QAC7B,WAAW,UAAU,OAAO;AAAA,MAC9B,CAAC;AAAA,MACD,UAAU;AAAA,MACV,EAAE,cAAc,qBAAqB,UAAU,YAAY,WAAW;AAAA,IACxE;AAAA,EACF,SAAS,OAAO;AACd,WAAO,0BAA0B,OAAO,UAAU;AAAA,EACpD;AACF;AAEA,eAAsB,KAAK,SAAkB,SAA0C;AACrF,SAAO,0BAA0B,SAAS,SAAS,8BAA8B,mBAAmB;AACtG;AAEO,MAAM,UAA2B,2BAA2B;AAAA,EACjE,KAAK;AAAA,EACL,SAAS;AAAA,EACT,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAAA,EAC9C,SAAS;AAAA,IACP,MAAM;AAAA,MACJ,SAAS;AAAA,MACT,WAAW,CAAC,EAAE,QAAQ,KAAK,aAAa,2BAA2B,QAAQ,wBAAwB,CAAC;AAAA,MACpG,QAAQ;AAAA,QACN,EAAE,QAAQ,KAAK,aAAa,gBAAgB,QAAQ,iBAAiB;AAAA,QACrE,EAAE,QAAQ,KAAK,aAAa,aAAa,QAAQ,iBAAiB;AAAA,QAClE,EAAE,QAAQ,KAAK,aAAa,sBAAsB,QAAQ,iBAAiB;AAAA,QAC3E,EAAE,QAAQ,KAAK,aAAa,iCAAiC,QAAQ,iBAAiB;AAAA,MACxF;AAAA,IACF;AAAA,EACF;AACF,CAAC;AAED,IAAO,gBAAQ,EAAE,KAAK;",
+  "names": []
+}

package/dist/modules/documents/api/[id]/attachments/[attachmentId]/route.js

@@ -0,0 +1,155 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { CrudHttpError } from "@open-mercato/shared/lib/crud/errors";
+import { findOneWithDecryption } from "@open-mercato/shared/lib/encryption/find";
+import { DocumentAttachment } from "../../../../data/entities.js";
+import { DOCUMENTS_ENTITY_IDS } from "../../../../lib/constants.js";
+import { resolveAttachmentServicePort } from "../../../../lib/attachmentServicePort.js";
+import { assertTier } from "../../../../lib/permissions.js";
+import {
+  assertDocumentNotArchived,
+  handleDocumentsRouteError,
+  resolveDocumentsContext,
+  routeErrorSchema,
+  runMutationGuardAfterSuccess,
+  validateMutationGuard,
+  withDocumentsContextErrors
+} from "../../../_shared.js";
+import {
+  buildDocumentsCommandRuntimeContext,
+  resolveDocumentsCommandBus
+} from "../../../_commands.js";
+const attachmentBinaryResponseSchema = z.unknown().describe("Binary file content");
+const attachmentDeleteResponseSchema = z.object({ ok: z.boolean() });
+const DOCUMENT_ATTACHMENT_PARTITION_CODE = "privateAttachments";
+const metadata = {
+  GET: { requireAuth: true, requireFeatures: ["documents.view"] },
+  DELETE: { requireAuth: true, requireFeatures: ["documents.edit"] }
+};
+async function resolveParams(context) {
+  const params = await context.params;
+  return { documentId: params.id, attachmentId: params.attachmentId };
+}
+async function loadDocumentAttachment(ctx, documentId, attachmentId) {
+  const documentAttachment = await findOneWithDecryption(
+    ctx.em,
+    DocumentAttachment,
+    {
+      documentId,
+      attachmentId,
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      deletedAt: null
+    },
+    void 0,
+    { tenantId: ctx.tenantId, organizationId: ctx.organizationId }
+  );
+  if (!documentAttachment) throw new CrudHttpError(404, { error: "Attachment not found" });
+  return documentAttachment;
+}
+async function GET(request, context) {
+  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 = {
+      "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");
+  }
+}
+async function DELETE(request, context) {
+  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 = {
+      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");
+  }
+}
+const openApi = 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 }
+      ]
+    }
+  }
+});
+var route_default = { GET, DELETE };
+export {
+  DELETE,
+  GET,
+  route_default as default,
+  metadata,
+  openApi
+};
+//# sourceMappingURL=route.js.map

package/dist/modules/documents/api/[id]/attachments/[attachmentId]/route.js.map

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

package/dist/modules/documents/api/[id]/attachments/route.js

@@ -0,0 +1,153 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { CrudHttpError } from "@open-mercato/shared/lib/crud/errors";
+import {
+  DOCUMENT_ATTACHMENT_UPLOAD_CONTEXT
+} from "../../../commands/attachments.js";
+import { DOCUMENTS_ENTITY_IDS } from "../../../lib/constants.js";
+import { readAttachmentUploadForm, resolveAttachmentServicePort } from "../../../lib/attachmentServicePort.js";
+import { assertTier } from "../../../lib/permissions.js";
+import {
+  assertDocumentNotArchived,
+  handleDocumentsRouteError,
+  loadScopedDocument,
+  resolveDocumentsContext,
+  routeErrorSchema,
+  runMutationGuardAfterSuccess,
+  validateMutationGuard,
+  withDocumentsContextErrors
+} from "../../_shared.js";
+import {
+  attachDocumentsOperationMetadata,
+  buildDocumentsCommandRuntimeContext,
+  resolveDocumentsCommandBus
+} from "../../_commands.js";
+const attachmentUploadBodySchema = z.object({
+  file: z.string().min(1).describe("Binary file payload supplied as multipart form-data")
+});
+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()
+});
+const metadata = {
+  POST: { requireAuth: true, requireFeatures: ["documents.edit"] }
+};
+async function resolveId(context) {
+  const params = await context.params;
+  return params.id;
+}
+function assertMultipartUpload(request) {
+  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) {
+  const file = form.get("file");
+  if (!(file instanceof File)) {
+    throw new CrudHttpError(400, { error: "File is required" });
+  }
+  return file;
+}
+async function POST(request, context) {
+  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" }
+      )
+    });
+    attachmentService.validateUpload({
+      fileName: guardPayload.fileName,
+      fileSize: guardPayload.fileSize
+    });
+    const buffer = Buffer.from(await file.arrayBuffer());
+    const commandInput = {
+      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("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");
+  }
+}
+const openApi = 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 }
+      ]
+    }
+  }
+});
+var route_default = { POST };
+export {
+  POST,
+  route_default as default,
+  metadata,
+  openApi
+};
+//# sourceMappingURL=route.js.map