@opengeni/api-router 3.0.1 → 4.0.0

package/src/fatal-process-boundary.ts

@@ -15,7 +15,8 @@ export type ApiFatalReasonKind =
   | "symbol"
   | "undefined";
 
-type ApiFatalObservability = Pick<Observability, "error" | "flush" | "startSpan">;
+type ApiFatalObservability = Pick<Observability, "error" | "flush" | "startSpan"> &
+  Partial<Pick<Observability, "recordFailureDiagnostic">>;
 
 type ApiFatalProcess = {
   on: (
@@ -69,10 +70,24 @@ export function installApiFatalProcessBoundary(
     reporting = true;
 
     const diagnostic = apiFatalDiagnostic(event, phase, reason, correlationId);
-    const message = apiFatalMessage(diagnostic);
+    let message = apiFatalMessage(diagnostic);
     const activeObservability = observability;
     try {
       if (activeObservability) {
+        try {
+          const diagnosticId = activeObservability.recordFailureDiagnostic?.({
+            code: FATAL_ERROR_CODES[event],
+            stage: phase,
+            retryDecision: "not_retryable",
+            error: reason,
+          });
+          if (diagnosticId) {
+            diagnostic.correlationId = diagnosticId;
+            message = apiFatalMessage(diagnostic);
+          }
+        } catch {
+          // Never replace the required fatal exit with an observer failure.
+        }
         let logged = false;
         try {
           activeObservability.error(message, diagnostic);

package/src/index.ts

@@ -16,6 +16,7 @@ import type {
 } from "@opengeni/contracts";
 import {
   assertRuntimeDatabasePosture,
+  isRetryableRuntimeDatabaseStartupError,
   createDb,
   markSessionWorkflowWakeDelivered,
   runtimeDatabaseReadyCheck,
@@ -28,7 +29,6 @@ import {
   type Observability,
 } from "@opengeni/observability";
 import { createObjectStorage } from "@opengeni/storage";
-import { createNativeRemoteMcpCredentialsPort } from "@opengeni/core/remote-mcp-credentials";
 import { isArtifactRuntimeConfigured } from "@opengeni/artifact-tool/runtime/development";
 import {
   resolveCatalogSettings,
@@ -266,7 +266,7 @@ export async function createTemporalWorkflowClient(
     startRigVerification: async ({ workspaceId, changeId, versionId, workflowId }) => {
       const targetId = changeId ?? versionId;
       if (!targetId) {
-        throw new Error("rig verification requires changeId or versionId");
+        throw new Error("sandbox environment verification requires changeId or versionId");
       }
       try {
         await temporal.workflow.start("rigVerificationWorkflow", {
@@ -363,7 +363,7 @@ export async function startApi(
     await retryStartupDependency(
       "PostgreSQL runtime posture",
       () => assertRuntimeDatabasePosture(dbClient.db, databasePosture),
-      { ...retryOptions, onRetry },
+      { ...retryOptions, onRetry, shouldRetry: isRetryableRuntimeDatabaseStartupError },
     );
     const resolvedCatalog = await retryStartupDependency(
       "model catalog",
@@ -421,7 +421,6 @@ export async function startApi(
   }
   const { app, routeDeps } = createAppComposition({
     settings,
-    connectionCredentials: createNativeRemoteMcpCredentialsPort(settings, dbClient.db),
     db: dbClient.db,
     bus,
     workflowClient: workflowClient.client,

package/src/integrations/atlassian.ts

@@ -1,7 +1,22 @@
+type AtlassianRequestAuthority = {
+  connectionUseContext?: Omit<AcceptedConnectionUseContext, "physicalRequestId" | "usePhase">;
+};
+
+import type { AcceptedConnectionUseContext } from "@opengeni/db";
+import {
+  withOrganizationIntegrationAcquisition,
+  withOrganizationIntegrationPolicyFence,
+} from "@opengeni/db/organization-integration-policy";
+import {
+  claimOAuthAcquisition,
+  finishOAuthAcquisition,
+  integrationSourceSelectionRequiresAcquisition,
+} from "./oauth-client";
 import {
   scheduledTaskKnowledgeSource,
   requireScheduledTaskKnowledgeSource,
   knowledgeSourceAgentConfig,
+  assertOrganizationIntegrationAllowed,
 } from "@opengeni/contracts";
 import type { Settings } from "@opengeni/config";
 import { createHash } from "node:crypto";
@@ -44,7 +59,6 @@ import {
   ConnectionDisconnectGenerationError,
   ConnectionDisconnectIdempotencyError,
   consumeIntegrationOAuthStateNonce,
-  claimConnectOperation,
   finishConnectOperation,
   getConnectAttempt,
   decryptEnvironmentValue,
@@ -132,6 +146,7 @@ export async function startAtlassianOAuth(
     externalContinuation?: ExternalActorContinuation;
   },
 ): Promise<AtlassianOAuthStartResponse> {
+  await withOrganizationIntegrationAcquisition(deps.db, input, ["atlassian"], async () => {});
   const oauth = requireAtlassianSettings(deps.settings);
   const existing = input.payload.connectionId
     ? await getConnectionMetadata(
@@ -208,12 +223,18 @@ export async function completeAtlassianOAuthCallback(
         operationId: `oauth:${state.nonce}`,
         inputDigest: createHash("sha256").update(input.state!).digest("hex"),
       };
-      const claim = await claimConnectOperation(deps.db, state, {
-        ...operation,
-        expectedRevision: stored.attempt.revision,
-        authorize: (tx, _attempt, origin) =>
-          requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
-      });
+      const claim = await claimOAuthAcquisition(
+        deps.db,
+        state,
+        {
+          ...operation,
+          expectedRevision: stored.attempt.revision,
+          authorize: (tx, _attempt, origin) =>
+            requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+        },
+        "atlassian",
+        Boolean(input.code && !input.error),
+      );
       if (claim.status === "replayed") return { redirectTo: exactReturnUrl, exactReturn: true };
     }
     await requireCallbackGrant(deps, state);
@@ -247,6 +268,7 @@ export async function completeAtlassianOAuthCallback(
     }
     if (input.error) throw new AtlassianCallbackError("provider_denied");
     if (!input.code) throw new AtlassianCallbackError("missing_code");
+    await withOrganizationIntegrationAcquisition(deps.db, state, ["atlassian"], async () => {});
 
     const oauth = requireAtlassianSettings(deps.settings);
     const redirectUri = `${baseUrl}/v1/integrations/atlassian/callback`;
@@ -360,36 +382,46 @@ export async function completeAtlassianOAuthCallback(
           });
     };
     if (operation) {
-      await finishConnectOperation(deps.db, acceptedState, {
-        ...operation,
-        authorize: (tx, _attempt, origin) =>
-          requireConnectOwnerAuthority(tx, acceptedState, "connections:write", origin),
-        commit: async (tx, current) => {
-          const connection = await persist(tx);
-          if (!connection) throw new AtlassianCallbackError("connection_conflict");
-          return {
-            ...current,
-            revision: current.revision + 1,
-            state: "complete",
-            credentialsCommitted: true,
-            nextAction: { type: "none" },
-            account: {
-              id: connection.id,
-              version: connection.version,
-              providerId: "atlassian",
-              label: profile.displayName ?? "Atlassian",
-              ownership: "personal",
-              status: "connected",
-            },
-          };
+      await finishOAuthAcquisition(
+        deps.db,
+        acceptedState,
+        {
+          ...operation,
+          authorize: (tx, _attempt, origin) =>
+            requireConnectOwnerAuthority(tx, acceptedState, "connections:write", origin),
+          commit: async (tx, current) => {
+            const connection = await persist(tx);
+            if (!connection) throw new AtlassianCallbackError("connection_conflict");
+            return {
+              ...current,
+              revision: current.revision + 1,
+              state: "complete",
+              credentialsCommitted: true,
+              nextAction: { type: "none" },
+              account: {
+                id: connection.id,
+                version: connection.version,
+                providerId: "atlassian",
+                label: profile.displayName ?? "Atlassian",
+                ownership: "personal",
+                status: "connected",
+              },
+            };
+          },
         },
-      });
+        "atlassian",
+      );
       return { redirectTo: exactReturnUrl!, exactReturn: true };
     }
-    const connection = await deps.db.transaction(async (tx) => {
-      await requireCallbackGrant({ ...deps, db: tx }, acceptedState);
-      return persist(tx);
-    });
+    const connection = await withOrganizationIntegrationAcquisition(
+      deps.db,
+      acceptedState,
+      ["atlassian"],
+      async (tx) => {
+        await requireCallbackGrant({ ...deps, db: tx }, acceptedState);
+        return persist(tx);
+      },
+    );
     if (!connection) throw new AtlassianCallbackError("connection_conflict");
     return {
       redirectTo: returnUrl(returnBaseUrl, state.returnPath, "connected", connection.id),
@@ -409,7 +441,11 @@ export async function completeAtlassianOAuthCallback(
 
 export async function browseAtlassianSources(
   deps: ApiRouteDeps,
-  input: { workspaceId: string; subjectId: string; connectionId: string },
+  input: AtlassianRequestAuthority & {
+    workspaceId: string;
+    subjectId: string;
+    connectionId: string;
+  },
 ) {
   const connection = await getConnectionMetadata(
     deps.db,
@@ -450,7 +486,7 @@ export async function browseAtlassianSources(
 
 export async function searchAtlassianLive(
   deps: ApiRouteDeps,
-  input: {
+  input: AtlassianRequestAuthority & {
     workspaceId: string;
     subjectId: string;
     connectionId: string;
@@ -553,7 +589,7 @@ export async function searchAtlassianLive(
 
 export async function getAtlassianLiveItem(
   deps: ApiRouteDeps,
-  input: {
+  input: AtlassianRequestAuthority & {
     workspaceId: string;
     subjectId: string;
     connectionId: string;
@@ -705,9 +741,28 @@ export async function saveAtlassianSources(
     initiatingSubjectId: input.subjectId,
   });
 
-  const available = (await browseAtlassianSources(deps, input)).items;
+  const requestedSelection = parsed.data.sources.map((source) => ({
+    ...source,
+    destination,
+    syncCadence: parsed.data.syncCadence,
+    syncEnabled: parsed.data.syncEnabled,
+    readPolicy: parsed.data.readPolicy,
+  }));
+  const acquiring = integrationSourceSelectionRequiresAcquisition(
+    metadata.selectedSources,
+    requestedSelection,
+  );
+  if (acquiring) {
+    await withOrganizationIntegrationAcquisition(deps.db, input, ["atlassian"], async () => {});
+  }
+
+  const available =
+    acquiring && parsed.data.sources.length
+      ? (await browseAtlassianSources(deps, input)).items
+      : [];
   const availableById = new Map(available.map((source) => [source.id, source]));
   const verified = parsed.data.sources.map((source) => {
+    if (!acquiring) return source;
     const current = availableById.get(source.id);
     if (
       !current ||
@@ -724,28 +779,39 @@ export async function saveAtlassianSources(
     return current;
   });
   const previousSources = metadata.selectedSources;
-  const updated = await transitionConnectionState(deps.db, {
-    workspaceId: input.workspaceId,
-    connectionId: existing.id,
-    visibleToSubjectId: input.subjectId,
-    expectedVersion: existing.version,
-    metadata: AtlassianConnectionMetadata.parse({
-      ...metadata,
-      documentDestination: destination,
-      selectedSources: verified.map((source) => ({
-        ...source,
-        destination,
-        syncCadence: parsed.data.syncCadence,
-        syncEnabled: parsed.data.syncEnabled,
-        configGeneration:
-          (previousSources.find((previous) => previous.id === source.id)?.configGeneration ?? 0) +
-          1,
-        readPolicy: parsed.data.readPolicy,
-        selectedAt: new Date().toISOString(),
-      })),
-    }),
-    updatedBySubjectId: input.subjectId,
-  });
+  const updated = await withOrganizationIntegrationPolicyFence(
+    deps.db,
+    input,
+    async (tx, policy) => {
+      // The exact generation checked by transitionConnectionState binds this
+      // comparison to the row being changed. Provider verification already ended.
+      if (integrationSourceSelectionRequiresAcquisition(previousSources, requestedSelection)) {
+        assertOrganizationIntegrationAllowed(policy, "atlassian");
+      }
+      return transitionConnectionState(tx, {
+        workspaceId: input.workspaceId,
+        connectionId: existing.id,
+        visibleToSubjectId: input.subjectId,
+        expectedVersion: existing.version,
+        metadata: AtlassianConnectionMetadata.parse({
+          ...metadata,
+          documentDestination: destination,
+          selectedSources: verified.map((source) => ({
+            ...source,
+            destination,
+            syncCadence: parsed.data.syncCadence,
+            syncEnabled: parsed.data.syncEnabled,
+            configGeneration:
+              (previousSources.find((previous) => previous.id === source.id)?.configGeneration ??
+                0) + 1,
+            readPolicy: parsed.data.readPolicy,
+            selectedAt: new Date().toISOString(),
+          })),
+        }),
+        updatedBySubjectId: input.subjectId,
+      });
+    },
+  );
   if (!updated) throw new HTTPException(409, { message: "Atlassian connection changed" });
   await materializeSchedules(deps, {
     ...input,
@@ -783,14 +849,27 @@ export async function transitionAtlassianLifecycle(
   if (target === "paused") {
     await deauthorizeConnectionSources(deps, connection, input.subjectId, "connection_paused");
   }
-  const updated = await transitionConnectionState(deps.db, {
-    workspaceId: input.workspaceId,
-    connectionId: input.connectionId,
-    visibleToSubjectId: input.subjectId,
-    expectedVersion: connection.version,
-    metadata: AtlassianConnectionMetadata.parse({ ...metadata, lifecycle: lifecycle(target) }),
-    updatedBySubjectId: input.subjectId,
-  });
+  const persist = (tx: Database) =>
+    transitionConnectionState(tx, {
+      workspaceId: input.workspaceId,
+      connectionId: input.connectionId,
+      visibleToSubjectId: input.subjectId,
+      expectedVersion: connection.version,
+      metadata: AtlassianConnectionMetadata.parse({ ...metadata, lifecycle: lifecycle(target) }),
+      updatedBySubjectId: input.subjectId,
+    });
+  const updated =
+    target === "active"
+      ? await withOrganizationIntegrationPolicyFence(
+          deps.db,
+          { accountId: connection.accountId, workspaceId: input.workspaceId },
+          (tx, policy) => {
+            if ((metadata.lifecycle?.state ?? "active") !== "active")
+              assertOrganizationIntegrationAllowed(policy, "atlassian");
+            return persist(tx);
+          },
+        )
+      : await persist(deps.db);
   if (!updated) throw new HTTPException(409, { message: "Atlassian connection changed" });
   await setSchedulePause(deps, input.workspaceId, input.connectionId, target === "paused");
   return updated;
@@ -1164,7 +1243,7 @@ async function materializeSchedules(
           action: { kind: "agent_turn" },
           runMode: "new_session_per_run",
           targetSessionId: null,
-          connectionAuthorities: [],
+          connectionAccounts: [],
           agentConfig: knowledgeSourceAgentConfig(action),
           variableSetId: null,
           environmentId: null,
@@ -1229,7 +1308,11 @@ async function materializeSchedules(
 
 async function browseJiraProjects(
   deps: ApiRouteDeps,
-  input: { workspaceId: string; subjectId: string; connectionId: string },
+  input: AtlassianRequestAuthority & {
+    workspaceId: string;
+    subjectId: string;
+    connectionId: string;
+  },
   site: AtlassianSite,
 ): Promise<AtlassianBrowseItem[]> {
   const items: AtlassianBrowseItem[] = [];
@@ -1275,7 +1358,11 @@ async function browseJiraProjects(
 
 async function browseConfluenceSpaces(
   deps: ApiRouteDeps,
-  input: { workspaceId: string; subjectId: string; connectionId: string },
+  input: AtlassianRequestAuthority & {
+    workspaceId: string;
+    subjectId: string;
+    connectionId: string;
+  },
   site: AtlassianSite,
 ): Promise<AtlassianBrowseItem[]> {
   const items: AtlassianBrowseItem[] = [];
@@ -1333,7 +1420,7 @@ export function confluenceNextUrl(cloudId: string, next: string): URL {
 
 async function atlassianApiRequest(
   deps: ApiRouteDeps,
-  input: {
+  input: AtlassianRequestAuthority & {
     workspaceId: string;
     subjectId: string;
     connectionId: string;
@@ -1354,9 +1441,20 @@ async function atlassianApiRequest(
   });
   const resolve = async (forceRefresh: boolean) =>
     await resolver({
-      workspaceId: input.workspaceId,
+      workspaceId: input.connectionUseContext?.workspaceId ?? input.workspaceId,
+      ...(input.connectionUseContext
+        ? {
+            connectionUseContext: {
+              ...input.connectionUseContext,
+              physicalRequestId: crypto.randomUUID(),
+              usePhase: "credential_resolution" as const,
+            },
+          }
+        : {}),
       subjectId: input.subjectId,
-      serverId: "atlassian-source-browser",
+      serverId: input.connectionUseContext
+        ? `atlassian:${input.connectionId}`
+        : "atlassian-source-browser",
       toolName: input.label,
       connectionRef: {
         providerDomain: ATLASSIAN_PROVIDER_DOMAIN,
@@ -1763,7 +1861,12 @@ function cqlString(value: string): string {
 
 async function readJiraLiveComments(
   deps: ApiRouteDeps,
-  input: { workspaceId: string; subjectId: string; connectionId: string; id: string },
+  input: AtlassianRequestAuthority & {
+    workspaceId: string;
+    subjectId: string;
+    connectionId: string;
+    id: string;
+  },
   cloudId: string,
 ) {
   const comments: Array<{ author: string | null; createdAt: string | null; body: string }> = [];
@@ -1796,7 +1899,12 @@ async function readJiraLiveComments(
 
 async function readConfluenceLiveComments(
   deps: ApiRouteDeps,
-  input: { workspaceId: string; subjectId: string; connectionId: string; id: string },
+  input: AtlassianRequestAuthority & {
+    workspaceId: string;
+    subjectId: string;
+    connectionId: string;
+    id: string;
+  },
   cloudId: string,
 ) {
   const comments: Array<{ createdAt: string | null; content: string }> = [];

package/src/integrations/fiken.ts

@@ -1,3 +1,5 @@
+import { withOrganizationIntegrationAcquisition } from "@opengeni/db/organization-integration-policy";
+import { claimOAuthAcquisition, finishOAuthAcquisition } from "./oauth-client";
 import { safeReturnPath } from "./oauth-return-path";
 import type { ApiRouteDeps } from "@opengeni/core";
 import type { Settings } from "@opengeni/config";
@@ -30,7 +32,6 @@ import {
   encryptEnvironmentValue,
   decryptEnvironmentValue,
   getConnectAttempt,
-  claimConnectOperation,
   finishConnectOperation,
   getConnectionMetadata,
   listConnectionsMetadata,
@@ -63,7 +64,9 @@ const MAX_DRAFT_LINES = 100;
 const COMPANY_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,127}$/;
 
 /** Shared native/embedded token adapter. Provider verification happens before
- * persistence; the caller reauthorizes inside its durable commit transaction. */
+ * persistence; the caller reauthorizes inside its durable commit transaction.
+ * That caller must acquire the organization policy fence for `fiken` BEFORE
+ * owner/tenancy locks and invoke the returned writer with that exact tx. */
 export async function prepareFikenTokenInstall(
   deps: ApiRouteDeps,
   grant: Pick<AccessGrant, "accountId" | "workspaceId" | "subjectId">,
@@ -71,6 +74,7 @@ export async function prepareFikenTokenInstall(
   expectedVersion?: number,
 ): Promise<(tx: Database) => Promise<ConnectionMetadata>> {
   const payload = FikenInstallRequest.parse(raw);
+  await withOrganizationIntegrationAcquisition(deps.db, grant, ["fiken"], async () => {});
   const key = requireEnvironmentEncryption(deps.settings);
   const existing = payload.connectionId
     ? await getConnectionMetadata(deps.db, grant.workspaceId, payload.connectionId, null)
@@ -1102,6 +1106,7 @@ export async function startFikenOAuth(
     connectAttemptId?: string;
   },
 ): Promise<FikenOAuthStartResponse> {
+  await withOrganizationIntegrationAcquisition(deps.db, input, ["fiken"], async () => {});
   const fiken = requireFikenOAuthSettings(deps.settings);
   const existing = input.payload.connectionId
     ? await getConnectionMetadata(deps.db, input.workspaceId, input.payload.connectionId, null)
@@ -1168,12 +1173,18 @@ export async function completeFikenOAuthCallback(
         operationId: `oauth:${state.nonce}`,
         inputDigest: createHash("sha256").update(input.state!).digest("hex"),
       };
-      const claim = await claimConnectOperation(deps.db, state, {
-        ...operation,
-        expectedRevision: stored.attempt.revision,
-        authorize: (tx, _attempt, origin) =>
-          requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
-      });
+      const claim = await claimOAuthAcquisition(
+        deps.db,
+        state,
+        {
+          ...operation,
+          expectedRevision: stored.attempt.revision,
+          authorize: (tx, _attempt, origin) =>
+            requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+        },
+        "fiken",
+        Boolean(input.code && !input.error),
+      );
       if (claim.status === "replayed") return { redirectTo: exactReturnUrl, exactReturn: true };
     }
     await requireFikenCallbackGrant(deps.db, state);
@@ -1217,6 +1228,7 @@ export async function completeFikenOAuthCallback(
     if (!input.code) {
       throw new FikenOAuthCallbackError("missing_code");
     }
+    await withOrganizationIntegrationAcquisition(deps.db, state, ["fiken"], async () => {});
     const fiken = requireFikenOAuthSettings(deps.settings);
     const key = requireEnvironmentEncryption(deps.settings);
     const fetchImpl = deps.fikenFetch ?? fetch;
@@ -1303,36 +1315,46 @@ export async function completeFikenOAuthCallback(
             createdBySubjectId: state!.subjectId,
           });
     if (operation) {
-      await finishConnectOperation(deps.db, state, {
-        ...operation,
-        authorize: (tx, _attempt, origin) =>
-          requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
-        commit: async (tx, current) => {
-          const connection = await persist(tx);
-          if (!connection) throw new FikenOAuthCallbackError("connection_conflict");
-          return {
-            ...current,
-            revision: current.revision + 1,
-            state: "complete",
-            credentialsCommitted: true,
-            nextAction: { type: "none" },
-            account: {
-              id: connection.id,
-              version: connection.version,
-              providerId: "fiken-oauth",
-              label: "Fiken",
-              ownership: "workspace",
-              status: "connected",
-            },
-          };
+      await finishOAuthAcquisition(
+        deps.db,
+        state,
+        {
+          ...operation,
+          authorize: (tx, _attempt, origin) =>
+            requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+          commit: async (tx, current) => {
+            const connection = await persist(tx);
+            if (!connection) throw new FikenOAuthCallbackError("connection_conflict");
+            return {
+              ...current,
+              revision: current.revision + 1,
+              state: "complete",
+              credentialsCommitted: true,
+              nextAction: { type: "none" },
+              account: {
+                id: connection.id,
+                version: connection.version,
+                providerId: "fiken-oauth",
+                label: "Fiken",
+                ownership: "workspace",
+                status: "connected",
+              },
+            };
+          },
         },
-      });
+        "fiken",
+      );
       return { redirectTo: exactReturnUrl!, exactReturn: true };
     }
-    const connection = await deps.db.transaction(async (tx) => {
-      await requireFikenCallbackGrant(tx, state!);
-      return persist(tx);
-    });
+    const connection = await withOrganizationIntegrationAcquisition(
+      deps.db,
+      state,
+      ["fiken"],
+      async (tx) => {
+        await requireFikenCallbackGrant(tx, state!);
+        return persist(tx);
+      },
+    );
     if (!connection) {
       throw new FikenOAuthCallbackError("connection_conflict");
     }