@opengeni/api-router 3.0.1 → 4.0.0

package/src/routes/files.ts

@@ -1,3 +1,4 @@
+import { readSessionAttachmentFiles } from "@opengeni/core";
 import { ZodError } from "zod";
 import {
   CompleteFileUploadResponse,
@@ -405,15 +406,28 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
   });
 
-  app.get("/v1/workspaces/:workspaceId/files/:fileId", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "files:read");
-    const file = await requireFileForSubject(db, {
+  const readRequestedFile = async (
+    c: Context,
+    grant: Awaited<ReturnType<typeof requireAccessGrant>>,
+  ) => {
+    const fileId = c.req.param("fileId") ?? "";
+    const sessionId = c.req.query("sessionId");
+    if (sessionId) {
+      if (!/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/iu.test(sessionId)) return null;
+      return (await readSessionAttachmentFiles(deps, grant, sessionId, [fileId]))[0] ?? null;
+    }
+    return requireFileForSubject(db, {
       accountId: grant.accountId,
-      workspaceId,
+      workspaceId: grant.workspaceId,
       subjectId: grant.subjectId,
-      fileId: c.req.param("fileId"),
+      fileId,
     }).catch(() => null);
+  };
+
+  app.get("/v1/workspaces/:workspaceId/files/:fileId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const file = await readRequestedFile(c, grant).catch(() => null);
     if (!file) {
       throw new HTTPException(404, { message: "file not found" });
     }
@@ -589,12 +603,7 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
         message: "object storage is not configured",
       });
     }
-    const file = await requireFileForSubject(db, {
-      accountId: grant.accountId,
-      workspaceId,
-      subjectId: grant.subjectId,
-      fileId: c.req.param("fileId"),
-    }).catch(() => null);
+    const file = await readRequestedFile(c, grant).catch(() => null);
     if (!file) {
       throw new HTTPException(404, { message: "file not found" });
     }

package/src/routes/github.ts

@@ -7,6 +7,7 @@ import {
   type GitHubInstallationBindingCandidate,
 } from "@opengeni/contracts";
 import { PersonalGitHubConnectionMetadata } from "@opengeni/contracts/personal-github";
+import { withOrganizationIntegrationAcquisition } from "@opengeni/db/organization-integration-policy";
 import {
   ListGitHubRepositoryBranchesQuery,
   VerifyPublicGitHubRepositoryRefRequest,
@@ -72,6 +73,10 @@ import {
   requireLegacyOAuthActor,
 } from "../connection-ownership";
 import { listPersonalGitHubConnections } from "../integrations/personal-github";
+import {
+  integrationCommitGrant,
+  type IntegrationCommitGrant,
+} from "../integrations/integration-commit-authority";
 import {
   isConsistentGitHubBindingCandidates,
   isConsistentGitHubBindingProof,
@@ -598,6 +603,7 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
           message: "GitHub OAuth state does not match this workspace",
         });
       }
+      await withOrganizationIntegrationAcquisition(db, grant, ["github-app"], async () => {});
       let candidates: GitHubInstallationBindingCandidate[] | null;
       try {
         candidates = deps.githubAppApi?.discoverInstallationBindingCandidates
@@ -652,6 +658,7 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
         message: "GitHub OAuth state does not match this workspace",
       });
     }
+    await withOrganizationIntegrationAcquisition(db, grant, ["github-app"], async () => {});
     let proof;
     try {
       proof = deps.githubAppApi?.authorizeInstallationBinding
@@ -681,22 +688,30 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
     const expiresAt = new Date((statePayload.iat + githubBindingStateMaxAgeSeconds) * 1_000);
     let bound;
     try {
-      bound = await bindAuthorizedGitHubInstallationRepositories(db, {
-        accountId: grant.accountId,
-        workspaceId: grant.workspaceId,
-        installationId,
-        githubAccountId: proof.installation.accountId,
-        accountLogin: proof.installation.accountLogin,
-        accountType: proof.installation.accountType,
-        linkedBySubjectId: grant.subjectId,
-        githubActorId: proof.actorId,
-        githubActorLogin: proof.actorLogin,
-        authorityKind: proof.authorityKind,
-        authorityCheckedAt,
-        authorityExpiresAt: expiresAt,
-        authorityNonce: statePayload.nonce,
-        repositoryIds,
-      });
+      bound = await withOrganizationIntegrationAcquisition(
+        db,
+        grant,
+        ["github-app"],
+        async (tx) => {
+          await grant.authorizeCommit(tx);
+          return bindAuthorizedGitHubInstallationRepositories(tx, {
+            accountId: grant.accountId,
+            workspaceId: grant.workspaceId,
+            installationId,
+            githubAccountId: proof.installation.accountId,
+            accountLogin: proof.installation.accountLogin,
+            accountType: proof.installation.accountType,
+            linkedBySubjectId: grant.subjectId,
+            githubActorId: proof.actorId,
+            githubActorLogin: proof.actorLogin,
+            authorityKind: proof.authorityKind,
+            authorityCheckedAt,
+            authorityExpiresAt: expiresAt,
+            authorityNonce: statePayload.nonce,
+            repositoryIds,
+          });
+        },
+      );
     } catch (error) {
       if (error instanceof GitHubInstallationAuthorityCommitError) {
         throw new HTTPException(409, { message: error.message });
@@ -913,18 +928,32 @@ async function requireGitHubManageGrant(
   deps: ApiRouteDeps,
   workspaceId: string,
   expectedState: GitHubSignedStatePayload,
-): Promise<AccessGrant> {
+): Promise<IntegrationCommitGrant> {
   try {
     const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "github:manage");
     requireLegacyOAuthActor(access);
-    return access.grant;
+    return integrationCommitGrant(access, ["github:manage"], {
+      settings: deps.settings,
+      authorizationHeader: c.req.header("authorization"),
+    });
   } catch (error) {
     if (!(error instanceof HTTPException) || error.status !== 401) {
       throw error;
     }
     const grant = githubBrowserGrantFromState(deps.settings, expectedState, workspaceId);
     if (grant) {
-      return grant;
+      return {
+        ...grant,
+        authorizeCommit: async () => {
+          const current = githubBrowserGrantFromState(deps.settings, expectedState, workspaceId);
+          if (
+            !current ||
+            current.accountId !== grant.accountId ||
+            current.subjectId !== grant.subjectId
+          )
+            throw new HTTPException(403, { message: "GitHub browser handoff expired or changed" });
+        },
+      };
     }
     throw error;
   }

package/src/routes/insights.ts

@@ -1,6 +1,8 @@
 import { InsightsRange, WorkspaceInsightsResponse } from "@opengeni/contracts";
 import {
   getWorkspaceInsights,
+  measureInsightsPhase,
+  workspaceInsightsPhaseMetricObserver,
   normalizeWorkspaceInsightsFilter,
   requireAccessGrant,
   WorkspaceInsightsFilterValidationError,
@@ -27,6 +29,7 @@ export function normalizeWorkspaceInsightsQueryFilter(
 
 export function registerInsightsRoutes(app: Hono, deps: ApiRouteDeps): void {
   const observeRequest = workspaceInsightsMetricObserver(deps.observability);
+  const observePhase = workspaceInsightsPhaseMetricObserver(deps.observability);
   app.get("/v1/workspaces/:workspaceId/insights", async (c) => {
     const startedAtMs = performance.now();
     const rangeRaw = c.req.query("range") ?? "week";
@@ -38,7 +41,9 @@ export function registerInsightsRoutes(app: Hono, deps: ApiRouteDeps): void {
 
     try {
       const workspaceId = c.req.param("workspaceId");
-      await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+      await measureInsightsPhase(observePhase, "auth", () =>
+        requireAccessGrant(c, deps, workspaceId, "workspace:admin"),
+      );
 
       const rangeParsed = InsightsRange.safeParse(rangeRaw);
       if (!rangeParsed.success) {
@@ -49,12 +54,17 @@ export function registerInsightsRoutes(app: Hono, deps: ApiRouteDeps): void {
       provider = normalizeWorkspaceInsightsQueryFilter(providerRaw, "provider");
       model = normalizeWorkspaceInsightsQueryFilter(modelRaw, "model");
 
-      const response = await getWorkspaceInsights(deps.db, deps.settings, {
-        workspaceId,
-        range: rangeParsed.data,
-        provider,
-        model,
-      });
+      const response = await getWorkspaceInsights(
+        deps.db,
+        deps.settings,
+        {
+          workspaceId,
+          range: rangeParsed.data,
+          provider,
+          model,
+        },
+        observePhase,
+      );
       c.header("cache-control", "private, no-store");
       const result = c.json(WorkspaceInsightsResponse.parse(response));
       outcome = "completed";

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";
@@ -179,20 +183,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,
         );
@@ -212,17 +226,27 @@ export function registerIntegrationFacetRoutes(app: Hono, deps: ApiRouteDeps): v
         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) {
@@ -264,6 +288,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/knowledge.ts

@@ -5,6 +5,7 @@ import {
   AgentLearningContext,
   AgentLearningOverridePatch,
   KnowledgeEntryListRequest,
+  KnowledgeSavePreparationRequest,
   KnowledgeReviewBatchListRequest,
   KnowledgeEntryBatchReviewRequest,
   AgentInstructionReviewRequest,
@@ -15,6 +16,7 @@ import {
 } from "@opengeni/contracts";
 import {
   prepareKnowledgeFile,
+  prepareKnowledgeSave,
   searchKnowledgeEntries,
   hasPermission,
   knowledgeContextForAccess,
@@ -125,7 +127,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) =>
@@ -173,6 +188,38 @@ 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,
+          KnowledgeSavePreparationRequest.parse(await c.req.json()),
+          () => deps.getDocumentServices().embedder,
+        ),
+      );
+    }),
+  );
   app.post(`${base}/search`, (c) =>
     run(c, false, async (context) =>
       c.json(