@opengeni/api-router 3.0.1 → 3.1.2

package/src/routes/integration-facets.ts

@@ -1,10 +1,13 @@
 import {
+  assertOrganizationIntegrationAllowed,
   IntegrationFacetMutationResult,
   IntegrationFacetRemovalResult,
   IntegrationInstanceFacetsResponse,
   MutateIntegrationFacetRequest,
   UpsertIntegrationFacetRequest,
 } from "@opengeni/contracts";
+import { withOrganizationIntegrationPolicyFence } from "@opengeni/db/organization-integration-policy";
+import { CORE_INTEGRATION_DEFINITIONS } from "@opengeni/capabilities";
 import {
   hasPermission,
   requireAccessGrant,
@@ -25,6 +28,7 @@ import {
   removeIntegrationFacet,
   replayCompletedIntegrationFacetOperation,
   setIntegrationFacetLifecycle,
+  type IntegrationFacetAcquisitionAuthorizer,
 } from "@opengeni/db";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
@@ -33,6 +37,7 @@ import {
   browseGoogleDriveFacetSource,
   saveGoogleDriveFacetSource,
 } from "../integrations/google-drive";
+import { parseRequestJson } from "../http/request-body";
 
 export function registerIntegrationFacetRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.get(
@@ -126,7 +131,7 @@ export function registerIntegrationFacetRoutes(app: Hono, deps: ApiRouteDeps): v
     async (c) => {
       const workspaceId = c.req.param("workspaceId");
       const grant = await requireAccessGrant(c, deps, workspaceId, "capabilities:manage");
-      const payload = UpsertIntegrationFacetRequest.parse(await c.req.json());
+      const payload = await parseRequestJson(c, UpsertIntegrationFacetRequest);
       const capabilityId = decoded(c.req.param("capabilityId"));
       const instanceKey = decoded(c.req.param("instanceKey"));
       const facetKey = decoded(c.req.param("facetKey"));
@@ -179,20 +184,30 @@ export function registerIntegrationFacetRoutes(app: Hono, deps: ApiRouteDeps): v
         }
         return c.json(
           IntegrationFacetMutationResult.parse(
-            await configureIntegrationFacet(deps.db, {
-              accountId: grant.accountId,
-              workspaceId,
-              subjectId: grant.subjectId,
-              capabilityId,
-              instanceKey,
-              facetKey,
-              displayName: payload.displayName,
-              config: payload.config,
-              ...(payload.expectedVersion !== undefined
-                ? { expectedVersion: payload.expectedVersion }
-                : {}),
-              idempotencyKey: payload.idempotencyKey,
-            }),
+            await withOrganizationIntegrationPolicyFence(
+              deps.db,
+              { accountId: grant.accountId, workspaceId },
+              (tx, policy) =>
+                configureIntegrationFacet(tx, {
+                  accountId: grant.accountId,
+                  workspaceId,
+                  subjectId: grant.subjectId,
+                  capabilityId,
+                  instanceKey,
+                  facetKey,
+                  displayName: payload.displayName,
+                  config: payload.config,
+                  ...(payload.expectedVersion !== undefined
+                    ? { expectedVersion: payload.expectedVersion }
+                    : {}),
+                  idempotencyKey: payload.idempotencyKey,
+                  beforeAcquire: async (_db, context) =>
+                    assertOrganizationIntegrationAllowed(
+                      policy,
+                      installedFacetIntegrationKey(context),
+                    ),
+                }),
+            ),
           ),
           payload.expectedVersion === undefined ? 201 : 200,
         );
@@ -208,21 +223,31 @@ export function registerIntegrationFacetRoutes(app: Hono, deps: ApiRouteDeps): v
       async (c) => {
         const workspaceId = c.req.param("workspaceId");
         const grant = await requireAccessGrant(c, deps, workspaceId, "capabilities:manage");
-        const payload = MutateIntegrationFacetRequest.parse(await c.req.json());
+        const payload = await parseRequestJson(c, MutateIntegrationFacetRequest);
         try {
           return c.json(
             IntegrationFacetMutationResult.parse(
-              await setIntegrationFacetLifecycle(deps.db, {
-                accountId: grant.accountId,
-                workspaceId,
-                subjectId: grant.subjectId,
-                capabilityId: decoded(c.req.param("capabilityId")),
-                instanceKey: decoded(c.req.param("instanceKey")),
-                facetKey: decoded(c.req.param("facetKey")),
-                action,
-                expectedVersion: payload.expectedVersion,
-                idempotencyKey: payload.idempotencyKey,
-              }),
+              await withOrganizationIntegrationPolicyFence(
+                deps.db,
+                { accountId: grant.accountId, workspaceId },
+                (tx, policy) =>
+                  setIntegrationFacetLifecycle(tx, {
+                    accountId: grant.accountId,
+                    workspaceId,
+                    subjectId: grant.subjectId,
+                    capabilityId: decoded(c.req.param("capabilityId")),
+                    instanceKey: decoded(c.req.param("instanceKey")),
+                    facetKey: decoded(c.req.param("facetKey")),
+                    action,
+                    expectedVersion: payload.expectedVersion,
+                    idempotencyKey: payload.idempotencyKey,
+                    beforeAcquire: async (_db, context) =>
+                      assertOrganizationIntegrationAllowed(
+                        policy,
+                        installedFacetIntegrationKey(context),
+                      ),
+                  }),
+              ),
             ),
           );
         } catch (error) {
@@ -237,7 +262,7 @@ export function registerIntegrationFacetRoutes(app: Hono, deps: ApiRouteDeps): v
     async (c) => {
       const workspaceId = c.req.param("workspaceId");
       const grant = await requireAccessGrant(c, deps, workspaceId, "capabilities:manage");
-      const payload = MutateIntegrationFacetRequest.parse(await c.req.json());
+      const payload = await parseRequestJson(c, MutateIntegrationFacetRequest);
       try {
         return c.json(
           IntegrationFacetRemovalResult.parse(
@@ -264,6 +289,23 @@ function decoded(value: string): string {
   return decodeURIComponent(value);
 }
 
+/** The DB context comes from the matching installed API facet and immutable
+ * server-authored version manifest, never request metadata or a provider domain.
+ */
+function installedFacetIntegrationKey(
+  context: Parameters<IntegrationFacetAcquisitionAuthorizer>[1],
+): string | null {
+  if (context.apiProtocol !== "openapi" && context.apiProtocol !== "graphql") return null;
+  if (context.definitionProvenance === "workspace") return `custom:${context.apiProtocol}`;
+  if (
+    context.definitionProvenance === "curated" &&
+    CORE_INTEGRATION_DEFINITIONS.some((definition) => definition.id === context.definitionId)
+  ) {
+    return context.definitionId;
+  }
+  return null;
+}
+
 function facetHttpError(error: unknown): HTTPException {
   if (error instanceof HTTPException) return error;
   if (error instanceof IntegrationFacetNotFoundError) {

package/src/routes/interaction-placement-message.ts

@@ -0,0 +1,12 @@
+/**
+ * The 422 a session gets when it asks for a computer or browser on a Connected
+ * Machine it is not currently placed on. Name the exact way to get there so an
+ * agent switches itself over instead of delegating or giving up, and keep it
+ * conditional because not every session is allowed to swap.
+ */
+export function wrongInteractionPlacementMessage(targetSandboxId: string): string {
+  return (
+    "The requested Connected Machine is not this session's current placement. " +
+    `Move the session to that machine before creating an interaction resource: if sandbox_swap is available, call it with target "${targetSandboxId}", retry, and swap back (target "session") when done.`
+  );
+}

package/src/routes/knowledge.ts

@@ -5,6 +5,7 @@ import {
   AgentLearningContext,
   AgentLearningOverridePatch,
   KnowledgeEntryListRequest,
+  KnowledgeSavePreparationRequest,
   KnowledgeReviewBatchListRequest,
   KnowledgeEntryBatchReviewRequest,
   AgentInstructionReviewRequest,
@@ -15,7 +16,11 @@ import {
 } from "@opengeni/contracts";
 import {
   prepareKnowledgeFile,
+  prepareKnowledgeSave,
   searchKnowledgeEntries,
+  KnowledgeVectorCreditsDisabledError,
+  KnowledgeVectorFundingError,
+  KnowledgeVectorQueryRejectedError,
   hasPermission,
   knowledgeContextForAccess,
   requireAccessGrantAuthorization,
@@ -40,11 +45,16 @@ import {
   reviewKnowledgeEntries,
   reviewAgentInstruction,
   listAgentInstructionReviews,
+  KnowledgeEntryIdRequiredError,
+  KnowledgeEntryIdTakenError,
 } from "@opengeni/db";
 import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import { z } from "zod";
 import { withAccessGrantSessionRlsContext } from "../access-grant-rls";
+import { ApiHttpError } from "../http/api-error";
+import { userContentSignedGetUrlOptions } from "../http/user-content";
+import { parseRequestJson } from "../http/request-body";
 
 const ReadSettings = z
   .object({
@@ -61,6 +71,36 @@ const WriteSettings = ReadSettings.extend({
 const Id = z.uuid();
 function knowledgeHttpError(error: unknown): never {
   if (error instanceof HTTPException) throw error;
+  if (error instanceof KnowledgeVectorFundingError)
+    throw new ApiHttpError(402, {
+      code: "payment_required",
+      message: error.message,
+      details: { code: error.code, keywordAvailable: true },
+    });
+  if (error instanceof KnowledgeVectorCreditsDisabledError)
+    throw new ApiHttpError(403, {
+      code: "forbidden",
+      message: error.message,
+      details: { code: error.code, keywordAvailable: true },
+    });
+  if (error instanceof KnowledgeVectorQueryRejectedError)
+    throw new ApiHttpError(error.code === "quota" ? 429 : 422, {
+      code: error.code === "quota" ? "limit_exceeded" : "validation_failed",
+      message: error.message,
+      details: { code: error.code, keywordAvailable: true },
+    });
+  if (error instanceof KnowledgeEntryIdTakenError)
+    throw new ApiHttpError(409, {
+      code: "conflict",
+      message: error.message,
+      details: { code: error.code },
+    });
+  if (error instanceof KnowledgeEntryIdRequiredError)
+    throw new ApiHttpError(422, {
+      code: "validation_failed",
+      message: error.message,
+      details: { code: error.code },
+    });
   if (error instanceof z.ZodError)
     throw new HTTPException(422, {
       message: error.issues[0]?.message ?? "Invalid Knowledge request",
@@ -83,20 +123,29 @@ export function registerKnowledgeRoutes(app: Hono, deps: ApiRouteDeps) {
     c: Context,
     write: boolean,
     fn: (context: Awaited<ReturnType<typeof knowledgeContextForAccess>>) => Promise<T>,
+    readPermission: "documents:search" | "workspace:read" = "documents:search",
   ) {
     try {
       const access = await requireAccessGrantAuthorization(
         c,
         deps,
         c.req.param("workspaceId")!,
-        write ? "documents:manage" : "documents:search",
+        write
+          ? "documents:manage"
+          : readPermission === "workspace:read"
+            ? undefined
+            : readPermission,
       );
+      // Preserve existing document-reader access to the settings read while
+      // admitting workspace readers to that one endpoint as well.
+      const permission = write
+        ? "documents:manage"
+        : readPermission === "workspace:read" &&
+            hasPermission(access.grant.permissions, "documents:search")
+          ? "documents:search"
+          : readPermission;
       return await withAccessGrantSessionRlsContext(deps, access.grant, async () => {
-        const context = await knowledgeContextForAccess(
-          deps,
-          access,
-          write ? "documents:manage" : "documents:search",
-        );
+        const context = await knowledgeContextForAccess(deps, access, permission);
         c.header("cache-control", "private, no-store");
         return fn(context);
       });
@@ -125,7 +174,20 @@ export function registerKnowledgeRoutes(app: Hono, deps: ApiRouteDeps) {
         throw new HTTPException(403, {
           message: "Source preparation is unavailable for this task",
         });
-      return c.json(await prepareKnowledgeFile(deps, context, Id.parse(c.req.param("fileId"))));
+      const body = await c.req.text();
+      let input: unknown = {};
+      try {
+        input = body ? JSON.parse(body) : {};
+      } catch {
+        throw new HTTPException(400, { message: "Invalid source preparation JSON" });
+      }
+      const { purpose } = z
+        .object({ purpose: z.enum(["evidence", "reference"]).default("evidence") })
+        .strict()
+        .parse(input);
+      return c.json(
+        await prepareKnowledgeFile(deps, context, Id.parse(c.req.param("fileId")), purpose),
+      );
     }),
   );
   app.post(`${base}/:entryId/file/download-url`, (c) =>
@@ -136,10 +198,10 @@ export function registerKnowledgeRoutes(app: Hono, deps: ApiRouteDeps) {
         context.workspaceId,
         "files:read",
       );
-      const { revisionId } = z
-        .object({ revisionId: z.uuid().optional() })
-        .strict()
-        .parse(await c.req.json());
+      const { revisionId } = await parseRequestJson(
+        c,
+        z.object({ revisionId: z.uuid().optional() }).strict(),
+      );
       const entryId = Id.parse(c.req.param("entryId"));
       const file = await getKnowledgeOriginalFile(deps.db, context, entryId, revisionId);
       if (!file) throw new HTTPException(404, { message: "Original file unavailable" });
@@ -151,7 +213,10 @@ export function registerKnowledgeRoutes(app: Hono, deps: ApiRouteDeps) {
         ))
       )
         throw new HTTPException(410, { message: "Original file bytes are unavailable" });
-      const signed = await deps.objectStorage.createGetUrl({ key: file.objectKey });
+      const signed = await deps.objectStorage.createGetUrl({
+        key: file.objectKey,
+        ...userContentSignedGetUrlOptions(file.contentType, file.filename),
+      });
       await recordAuditEvent(deps.db, {
         accountId: context.accountId,
         workspaceId: context.workspaceId,
@@ -173,14 +238,49 @@ export function registerKnowledgeRoutes(app: Hono, deps: ApiRouteDeps) {
       );
     }),
   );
+  app.post(`${base}/prepare-save`, (c) =>
+    run(c, false, async (context) => {
+      if (context.actor.kind === "agent") {
+        const access = await requireAccessGrantAuthorization(
+          c,
+          deps,
+          context.workspaceId,
+          "documents:search",
+        );
+        const selected = access.grant.metadata?.firstPartyMcpTools as
+          | FirstPartyMcpToolName[]
+          | undefined;
+        if (
+          !selected ||
+          !allowedFirstPartyMcpToolsForSession(deps.settings, selected).includes(
+            "knowledge_prepare_save",
+          )
+        )
+          throw new HTTPException(403, {
+            message: "Knowledge preparation is unavailable for this task",
+          });
+      }
+      return c.json(
+        await prepareKnowledgeSave(
+          deps.db,
+          context,
+          await parseRequestJson(c, KnowledgeSavePreparationRequest),
+          () => deps.getDocumentServices().embedder,
+          undefined,
+          deps.settings,
+        ),
+      );
+    }),
+  );
   app.post(`${base}/search`, (c) =>
     run(c, false, async (context) =>
       c.json(
         await searchKnowledgeEntries(
           deps.db,
           context,
-          KnowledgeEntryListRequest.parse(await c.req.json()),
+          await parseRequestJson(c, KnowledgeEntryListRequest),
           () => deps.getDocumentServices().embedder,
+          deps.settings,
         ),
       ),
     ),
@@ -206,7 +306,7 @@ export function registerKnowledgeRoutes(app: Hono, deps: ApiRouteDeps) {
         await reviewKnowledgeEntries(
           deps.db,
           context,
-          KnowledgeEntryBatchReviewRequest.parse(await c.req.json()),
+          await parseRequestJson(c, KnowledgeEntryBatchReviewRequest),
         ),
       ),
     ),
@@ -223,6 +323,7 @@ export function registerKnowledgeRoutes(app: Hono, deps: ApiRouteDeps) {
             ...(query.limit ? { limit: Number(query.limit) } : {}),
           }),
           () => deps.getDocumentServices().embedder,
+          deps.settings,
         ),
       );
     }),
@@ -232,7 +333,7 @@ export function registerKnowledgeRoutes(app: Hono, deps: ApiRouteDeps) {
       const result = await saveKnowledgeEntry(
         deps.db,
         context,
-        KnowledgeEntrySaveRequest.parse(await c.req.json()),
+        await parseRequestJson(c, KnowledgeEntrySaveRequest),
       );
       return c.json(result, result.replayed ? 200 : 201);
     }),
@@ -290,10 +391,10 @@ export function registerKnowledgeRoutes(app: Hono, deps: ApiRouteDeps) {
   );
   app.post(`${base}/:entryId/archive`, (c) =>
     run(c, true, async (context) => {
-      const request = z
-        .object({ operationId: Id, expectedVersion: z.number().int().positive() })
-        .strict()
-        .parse(await c.req.json());
+      const request = await parseRequestJson(
+        c,
+        z.object({ operationId: Id, expectedVersion: z.number().int().positive() }).strict(),
+      );
       return c.json(
         await archiveKnowledgeEntry(deps.db, context, {
           ...request,
@@ -333,18 +434,26 @@ export function registerKnowledgeRoutes(app: Hono, deps: ApiRouteDeps) {
         await reviewAgentInstruction(
           deps.db,
           await instructionReviewContext(c, context),
-          AgentInstructionReviewRequest.parse(await c.req.json()),
+          await parseRequestJson(c, AgentInstructionReviewRequest),
         ),
       ),
     ),
   );
   app.post(`${learning}/read`, (c) =>
-    run(c, false, async (context) => {
-      const request = ReadSettings.parse(await c.req.json());
-      return c.json(
-        await getAgentLearningSettings(deps.db, context, request.scope, request.source),
-      );
-    }),
+    // Members can inspect the settings relevant to their admitted workspace or
+    // owner context without gaining Knowledge search or settings-write access.
+    // The database still requires a human and checks each source's owner layer.
+    run(
+      c,
+      false,
+      async (context) => {
+        const request = await parseRequestJson(c, ReadSettings);
+        return c.json(
+          await getAgentLearningSettings(deps.db, context, request.scope, request.source),
+        );
+      },
+      "workspace:read",
+    ),
   );
   app.get(`${learning}/overrides`, (c) =>
     run(c, false, async (context) => {
@@ -357,7 +466,7 @@ export function registerKnowledgeRoutes(app: Hono, deps: ApiRouteDeps) {
   );
   app.post(learning, (c) =>
     run(c, false, async (context) => {
-      const request = WriteSettings.parse(await c.req.json());
+      const request = await parseRequestJson(c, WriteSettings);
       if (context.actor.kind !== "human")
         throw new HTTPException(403, { message: "Agents cannot change learning settings" });
       const access = await requireAccessGrantAuthorization(c, deps, context.workspaceId);