@opengeni/api-router 0.30.3 → 2.2.0-canary.0

package/src/routes/documents.ts

@@ -4,17 +4,31 @@ import {
   CreateKnowledgeMemoryRequest,
   CreateDocumentBaseRequest,
   Document,
+  DocumentAuthorityReclassification,
   DocumentBase,
+  DocumentDefaultCollectionBackfill,
+  DocumentDefaultCollectionBackfillAudit,
+  GetDocumentDefaultCollectionBackfillAuditQuery,
   DocumentSearchRequest,
   DocumentSearchResponse,
+  FileAsset,
+  FileDownloadUrlResponse,
   KnowledgeMemory,
   KnowledgeMemorySearchRequest,
+  ListDocumentAuthorityReclassificationsQuery,
+  ListDocumentAuthorityReclassificationsResponse,
+  ListDocumentDefaultCollectionBackfillRunsResponse,
+  ListDocumentMigrationAuditQuery,
+  ListOrganizationDocumentAuthorityReclassificationsResponse,
   MoveDocumentRequest,
+  ReclassifyDocumentAuthorityRequest,
+  RunDocumentDefaultCollectionBackfillRequest,
   UpdateKnowledgeMemoryRequest,
   WorkspaceMemorySearchRequest,
   WorkspaceMemorySearchResponse,
 } from "@opengeni/contracts";
 import {
+  recordAuditEvent,
   completeFileUpload,
   createFileUpload,
   createKnowledgeMemory,
@@ -29,11 +43,19 @@ import {
   deleteDocumentFromBase,
   ensureDefaultBase,
   getDocument,
+  getDocumentOriginalFile,
   getDocumentBase,
+  getDocumentDefaultCollectionBackfillAudit,
+  listAccessibleDocuments,
+  listDocumentAuthorityReclassifications,
+  listDocumentDefaultCollectionBackfillRuns,
   listDocumentBasesEnsuringDefault,
   listDocuments,
+  listOrganizationDocumentAuthorityReclassifications,
   moveDocumentToBase,
   queueDocumentForReindex,
+  reclassifyDocumentAuthority,
+  runDocumentDefaultCollectionBackfill,
   searchEffectiveDocuments,
 } from "@opengeni/documents";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
@@ -41,6 +63,7 @@ import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import {
   requireAccessGrant,
+  requireAccountAdminAuthorizationStamp,
   requireAccessGrantAuthorization,
   saveWorkspaceMemoryWithSlackPublication,
 } from "@opengeni/core";
@@ -87,6 +110,136 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
     return c.json(DocumentBase.parse(base));
   });
 
+  app.post("/v1/workspaces/:workspaceId/document-default-collection-backfills", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "documents:manage",
+    );
+    if (!hasAccountAdminAuthority(authorization)) {
+      throw new HTTPException(403, { message: "missing permission: account:admin" });
+    }
+    const accountAdminAuthorization = requireAccountAdminAuthorizationStamp(authorization);
+    const payload = RunDocumentDefaultCollectionBackfillRequest.parse(await c.req.json());
+    try {
+      return c.json(
+        DocumentDefaultCollectionBackfill.parse(
+          await runDocumentDefaultCollectionBackfill(db, {
+            ...payload,
+            accountId: authorization.grant.accountId,
+            workspaceId,
+            actorSubjectId: authorization.grant.subjectId,
+            accountAdminAuthorization,
+          }),
+        ),
+      );
+    } catch (error) {
+      throw documentHttpException(error);
+    }
+  });
+
+  app.get("/v1/workspaces/:workspaceId/document-default-collection-backfills", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "documents:manage",
+    );
+    if (!hasAccountAdminAuthority(authorization)) {
+      throw new HTTPException(403, { message: "missing permission: account:admin" });
+    }
+    const query = ListDocumentMigrationAuditQuery.safeParse(c.req.query());
+    if (!query.success) {
+      throw new HTTPException(400, { message: "invalid document migration audit query" });
+    }
+    try {
+      return c.json(
+        ListDocumentDefaultCollectionBackfillRunsResponse.parse(
+          await listDocumentDefaultCollectionBackfillRuns(db, {
+            accountId: authorization.grant.accountId,
+            workspaceId,
+            actorSubjectId: authorization.grant.subjectId,
+            accountAdminAuthorization: requireAccountAdminAuthorizationStamp(authorization),
+            ...query.data,
+          }),
+        ),
+      );
+    } catch (error) {
+      throw documentHttpException(error);
+    }
+  });
+
+  app.get("/v1/workspaces/:workspaceId/document-default-collection-backfills/:runId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "documents:manage",
+    );
+    if (!hasAccountAdminAuthority(authorization)) {
+      throw new HTTPException(403, { message: "missing permission: account:admin" });
+    }
+    const runId = RunDocumentDefaultCollectionBackfillRequest.shape.runId.safeParse(
+      c.req.param("runId"),
+    );
+    const query = GetDocumentDefaultCollectionBackfillAuditQuery.safeParse(c.req.query());
+    if (!runId.success || !query.success) {
+      throw new HTTPException(400, { message: "invalid document migration audit query" });
+    }
+    try {
+      return c.json(
+        DocumentDefaultCollectionBackfillAudit.parse(
+          await getDocumentDefaultCollectionBackfillAudit(db, {
+            accountId: authorization.grant.accountId,
+            workspaceId,
+            actorSubjectId: authorization.grant.subjectId,
+            accountAdminAuthorization: requireAccountAdminAuthorizationStamp(authorization),
+            runId: runId.data,
+            ...query.data,
+          }),
+        ),
+      );
+    } catch (error) {
+      throw documentHttpException(error);
+    }
+  });
+
+  app.get("/v1/workspaces/:workspaceId/document-authority-reclassifications", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      c,
+      deps,
+      workspaceId,
+      "documents:manage",
+    );
+    if (!hasAccountAdminAuthority(authorization)) {
+      throw new HTTPException(403, { message: "missing permission: account:admin" });
+    }
+    const query = ListDocumentMigrationAuditQuery.safeParse(c.req.query());
+    if (!query.success) {
+      throw new HTTPException(400, { message: "invalid document migration audit query" });
+    }
+    try {
+      return c.json(
+        ListOrganizationDocumentAuthorityReclassificationsResponse.parse(
+          await listOrganizationDocumentAuthorityReclassifications(db, {
+            accountId: authorization.grant.accountId,
+            workspaceId,
+            actorSubjectId: authorization.grant.subjectId,
+            accountAdminAuthorization: requireAccountAdminAuthorizationStamp(authorization),
+            ...query.data,
+          }),
+        ),
+      );
+    } catch (error) {
+      throw documentHttpException(error);
+    }
+  });
+
   app.post("/v1/workspaces/:workspaceId/document-bases/:baseId/documents", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "documents:manage");
@@ -161,6 +314,148 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
   });
 
+  app.get("/v1/workspaces/:workspaceId/documents", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "documents:search");
+    return c.json(
+      (
+        await listAccessibleDocuments(db, workspaceId, {
+          viewerSubjectId: grant.subjectId,
+        })
+      ).map((document) => Document.parse(document)),
+    );
+  });
+
+  app.post(
+    "/v1/workspaces/:workspaceId/documents/:documentId/authority-reclassifications",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const authorization = await requireAccessGrantAuthorization(
+        c,
+        deps,
+        workspaceId,
+        "documents:manage",
+      );
+      const payload = ReclassifyDocumentAuthorityRequest.parse(await c.req.json());
+      const accountAdminAuthorized = hasAccountAdminAuthority(authorization);
+      const accountAdminAuthorization = accountAdminAuthorized
+        ? requireAccountAdminAuthorizationStamp(authorization)
+        : null;
+      try {
+        const document = await getDocument(db, workspaceId, c.req.param("documentId"), {
+          viewerSubjectId: authorization.grant.subjectId,
+        });
+        if (!document) throw new HTTPException(404, { message: "document not found" });
+        if (
+          (document.authorityKind === "organization" ||
+            payload.targetAuthorityKind === "organization") &&
+          !accountAdminAuthorization
+        ) {
+          throw new HTTPException(403, { message: "missing permission: account:admin" });
+        }
+        return c.json(
+          DocumentAuthorityReclassification.parse(
+            await reclassifyDocumentAuthority(db, {
+              ...payload,
+              accountId: authorization.grant.accountId,
+              workspaceId,
+              documentId: document.id,
+              actorSubjectId: authorization.grant.subjectId,
+              accountAdminAuthorization,
+            }),
+          ),
+        );
+      } catch (error) {
+        if (error instanceof HTTPException) throw error;
+        throw documentHttpException(error);
+      }
+    },
+  );
+
+  app.get(
+    "/v1/workspaces/:workspaceId/documents/:documentId/authority-reclassifications",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "documents:manage");
+      try {
+        const query = ListDocumentAuthorityReclassificationsQuery.parse(c.req.query());
+        return c.json(
+          ListDocumentAuthorityReclassificationsResponse.parse(
+            await listDocumentAuthorityReclassifications(db, {
+              accountId: grant.accountId,
+              workspaceId,
+              documentId: c.req.param("documentId"),
+              actorSubjectId: grant.subjectId,
+              ...query,
+            }),
+          ),
+        );
+      } catch (error) {
+        throw documentHttpException(error);
+      }
+    },
+  );
+
+  app.get("/v1/workspaces/:workspaceId/documents/:documentId/original-file", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "documents:search");
+    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const file = await getDocumentOriginalFile(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      documentId: c.req.param("documentId"),
+      access: { viewerSubjectId: grant.subjectId },
+    });
+    if (!file) {
+      throw new HTTPException(404, { message: "document file not found" });
+    }
+    return c.json(FileAsset.parse(file));
+  });
+
+  app.post(
+    "/v1/workspaces/:workspaceId/documents/:documentId/original-file/download-url",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "documents:search");
+      await requireAccessGrant(c, deps, workspaceId, "files:read");
+      if (!objectStorage) {
+        throw new HTTPException(503, { message: "object storage is not configured" });
+      }
+      const file = await getDocumentOriginalFile(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        documentId: c.req.param("documentId"),
+        access: { viewerSubjectId: grant.subjectId },
+      });
+      if (!file) {
+        throw new HTTPException(404, { message: "document file not found" });
+      }
+      if (file.status !== "ready") {
+        throw new HTTPException(409, { message: `file is ${file.status}` });
+      }
+      const signed = await objectStorage.createGetUrl({ key: file.objectKey });
+      await recordAuditEvent(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        subjectId: grant.subjectId,
+        action: "file.signed_url.issued",
+        targetType: "workspace_document",
+        targetId: c.req.param("documentId"),
+        metadata: {
+          fileId: file.id,
+          kind: "document_original",
+          expiresAt: signed.expiresAt.toISOString(),
+        },
+      });
+      return c.json(
+        FileDownloadUrlResponse.parse({
+          url: signed.url,
+          expiresAt: signed.expiresAt.toISOString(),
+        }),
+      );
+    },
+  );
+
   app.delete(
     "/v1/workspaces/:workspaceId/document-bases/:baseId/documents/:documentId",
     async (c) => {
@@ -212,7 +507,9 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
       const { grant } = authorization;
       const organizationAuthorityGranted = hasAccountAdminAuthority(authorization);
       if (!objectStorage) {
-        throw new HTTPException(503, { message: "object storage is not configured" });
+        throw new HTTPException(503, {
+          message: "object storage is not configured",
+        });
       }
       await requireLimit(deps, {
         accountId: grant.accountId,
@@ -246,7 +543,9 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
         const indexed =
           (await documentIndexer.indexDocument({
             accountId: grant.accountId,
-            workspaceId,
+            // The requested workspace authorizes the human operation; the
+            // immutable ingestion workspace remains the indexing authority.
+            workspaceId: queued.workspaceId,
             documentId: document.id,
             authorityKind: document.authorityKind,
             authorityWorkspaceId: document.authorityWorkspaceId,
@@ -651,13 +950,19 @@ export function registerDocumentRoutes(app: Hono, deps: ApiRouteDeps): void {
     const grant = await requireAccessGrant(c, deps, workspaceId, "documents:search");
     const sessionId =
       typeof grant.metadata?.sessionId === "string" ? grant.metadata.sessionId : undefined;
+    const attemptId =
+      typeof grant.metadata?.attemptId === "string" ? grant.metadata.attemptId : undefined;
     const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
     const server = buildDocumentsMcpServer(
       db,
       grant.accountId,
       workspaceId,
       getDocumentServices(),
-      { createdBySessionId: sessionId, initiatingSubjectId: grant.subjectId },
+      {
+        createdBySessionId: sessionId,
+        attemptId,
+        initiatingSubjectId: grant.subjectId,
+      },
     );
     await server.connect(transport);
     return await transport.handleRequest(c.req.raw);
@@ -682,16 +987,47 @@ function dropFilename(preferred: string | undefined): string {
 }
 
 function documentHttpException(error: unknown): HTTPException {
-  const message = error instanceof Error ? error.message : String(error);
+  const message = documentDomainErrorMessage(error);
   if (message.includes("organization document") && message.includes("exact account authority")) {
     return new HTTPException(403, { message: "missing permission: account:admin" });
   }
   if (message.includes("not found")) {
     return new HTTPException(404, { message });
   }
+  if (message.includes("document Default collection backfill audit run is unavailable")) {
+    return new HTTPException(404, { message });
+  }
   if (message.includes("already exists")) {
     return new HTTPException(409, { message });
   }
+  if (
+    message.includes("operation id was reused") ||
+    message.includes("authority changed before reclassification") ||
+    message.includes("run identity mismatch")
+  ) {
+    return new HTTPException(409, { message });
+  }
+  if (
+    message.includes("reclassification requires") ||
+    message.includes("backfill requires organization administration") ||
+    message.includes("document migration audit requires organization administration") ||
+    message.includes("document migration audit scope is invalid")
+  ) {
+    return new HTTPException(403, { message });
+  }
+  if (
+    message.includes("reclassification input is invalid") ||
+    message.includes("reclassification authority is invalid") ||
+    message.includes("invalid document authority receipt cursor") ||
+    message.includes("document authority receipt limit") ||
+    message.includes("invalid document migration audit cursor") ||
+    message.includes("document migration audit cursor is invalid") ||
+    message.includes("document migration audit limit") ||
+    message.includes("document migration audit authority is incomplete") ||
+    message.includes("document Default collection backfill audit run id is required")
+  ) {
+    return new HTTPException(400, { message });
+  }
   if (message.includes("no suggested base")) {
     return new HTTPException(422, { message });
   }
@@ -711,6 +1047,19 @@ function documentHttpException(error: unknown): HTTPException {
   return new HTTPException(500, { message });
 }
 
+function documentDomainErrorMessage(error: unknown): string {
+  let current: unknown = error;
+  let message = error instanceof Error ? error.message : String(error);
+  const seen = new Set<unknown>();
+  while (current && typeof current === "object" && !seen.has(current) && seen.size < 8) {
+    seen.add(current);
+    const record = current as { cause?: unknown; message?: unknown };
+    if (typeof record.message === "string") message = record.message;
+    current = record.cause;
+  }
+  return message;
+}
+
 function hasAccountAdminAuthority(
   authorization: Awaited<ReturnType<typeof requireAccessGrantAuthorization>>,
 ): boolean {

package/src/routes/editable-artifacts.ts

@@ -78,9 +78,13 @@ const ListEditableArtifactsQuery = z
 const MintEditableArtifactLiveTicketRequest = z
   .object({
     replicaId: ReplicaId,
-    protocolVersion: PositiveProtocolVersion,
+    modality: z.enum(["document", "spreadsheet", "presentation"]),
+    liveProtocolVersion: PositiveProtocolVersion,
     kernelVersion: VersionName,
     modelSchemaVersion: PositiveModelSchemaVersion,
+    snapshotVersion: PositiveProtocolVersion,
+    commandProtocolVersion: PositiveProtocolVersion,
+    committedTransactionProtocolVersion: PositiveProtocolVersion,
   })
   .strict();
 
@@ -482,9 +486,13 @@ export function registerEditableArtifactRoutes(
         scope,
         actor,
         artifactId,
-        protocolVersion: body.protocolVersion,
+        modality: body.modality,
+        liveProtocolVersion: body.liveProtocolVersion,
         kernelVersion: body.kernelVersion,
         modelSchemaVersion: body.modelSchemaVersion,
+        snapshotVersion: body.snapshotVersion,
+        commandProtocolVersion: body.commandProtocolVersion,
+        committedTransactionProtocolVersion: body.committedTransactionProtocolVersion,
         allowEdit: hasPermission(grant.permissions, "artifacts:publish"),
       });
     } catch (error) {
@@ -496,7 +504,7 @@ export function registerEditableArtifactRoutes(
       !parsedTicket.success ||
       parsedTicket.data.artifactId !== artifactId ||
       parsedTicket.data.replicaId !== actor.replicaId ||
-      parsedTicket.data.protocolVersion !== body.protocolVersion ||
+      parsedTicket.data.protocolVersion !== body.liveProtocolVersion ||
       Date.parse(parsedTicket.data.expiresAt) <= Date.now()
     ) {
       throw new Error("Editable artifact application returned an invalid live ticket");