@opengeni/api-router 3.0.1 → 3.1.2

package/src/integrations/atlassian.ts

@@ -1,7 +1,21 @@
+type AtlassianRequestAuthority = {
+  connectionUseContext?: Omit<AcceptedConnectionUseContext, "physicalRequestId" | "usePhase">;
+};
+
+import type { AcceptedConnectionUseContext } from "@opengeni/db";
+import {
+  withOrganizationIntegrationAcquisition,
+  withOrganizationIntegrationPolicyFence,
+} from "@opengeni/db/organization-integration-policy";
+import {
+  claimOAuthAcquisition,
+  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 +58,6 @@ import {
   ConnectionDisconnectGenerationError,
   ConnectionDisconnectIdempotencyError,
   consumeIntegrationOAuthStateNonce,
-  claimConnectOperation,
   finishConnectOperation,
   getConnectAttempt,
   decryptEnvironmentValue,
@@ -70,6 +83,10 @@ import { atlassianKnowledgeSourceIdentity } from "@opengeni/documents/atlassian"
 import { createSignedState, readSignedState } from "@opengeni/github";
 import { readResponseJsonBounded, type FetchLike } from "@opengeni/network";
 import { HTTPException } from "hono/http-exception";
+import {
+  ATLASSIAN_NATIVE_RETIRED_MESSAGE,
+  ATLASSIAN_NATIVE_RETIRED_REASON,
+} from "@opengeni/contracts/atlassian-native-retirement";
 import {
   personalOnlyConnectionPrincipalMessage,
   personalOwnerStateAccepted,
@@ -78,6 +95,7 @@ import {
 } from "../connection-ownership";
 import {
   integrationBaseUrl,
+  oauthStateFailureReturn,
   oauthStateTtlMs,
   requireIntegrationsStateSecret,
 } from "./oauth-client";
@@ -132,6 +150,8 @@ export async function startAtlassianOAuth(
     externalContinuation?: ExternalActorContinuation;
   },
 ): Promise<AtlassianOAuthStartResponse> {
+  assertNativeAtlassianAvailable();
+  await withOrganizationIntegrationAcquisition(deps.db, input, ["atlassian"], async () => {});
   const oauth = requireAtlassianSettings(deps.settings);
   const existing = input.payload.connectionId
     ? await getConnectionMetadata(
@@ -208,12 +228,19 @@ 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",
+        // Retirement only settles this attempt; it acquires no integration.
+        false,
+      );
       if (claim.status === "replayed") return { redirectTo: exactReturnUrl, exactReturn: true };
     }
     await requireCallbackGrant(deps, state);
@@ -225,7 +252,7 @@ export async function completeAtlassianOAuthCallback(
       expiresAt: new Date(state.iat * 1000 + oauthStateTtlMs),
       now: new Date(),
     });
-    if (!consumed) throw new AtlassianCallbackError("state_reused");
+    if (!consumed) throw new AtlassianCallbackError("state_replayed");
     if (operation && (input.error || !input.code)) {
       await finishConnectOperation(deps.db, state, {
         ...operation,
@@ -247,6 +274,30 @@ export async function completeAtlassianOAuthCallback(
     }
     if (input.error) throw new AtlassianCallbackError("provider_denied");
     if (!input.code) throw new AtlassianCallbackError("missing_code");
+    // An authorization started on an older release must not exchange or save
+    // a native grant after retirement. Preserve exact Connect navigation and
+    // settle the pending attempt so it does not remain stuck authorizing.
+    if (operation) {
+      await finishConnectOperation(deps.db, state, {
+        ...operation,
+        authorize: (tx, _attempt, origin) =>
+          requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+        commit: async (_tx, current) => ({
+          ...current,
+          revision: current.revision + 1,
+          state: "failed",
+          nextAction: { type: "none" },
+          error: {
+            code: ATLASSIAN_NATIVE_RETIRED_REASON,
+            message: ATLASSIAN_NATIVE_RETIRED_MESSAGE,
+            retryable: false,
+          },
+        }),
+      });
+      return { redirectTo: exactReturnUrl!, exactReturn: true };
+    }
+    assertNativeAtlassianAvailable();
+    await withOrganizationIntegrationAcquisition(deps.db, state, ["atlassian"], async () => {});
 
     const oauth = requireAtlassianSettings(deps.settings);
     const redirectUri = `${baseUrl}/v1/integrations/atlassian/callback`;
@@ -359,49 +410,30 @@ export async function completeAtlassianOAuthCallback(
             createdBySubjectId: state.subjectId,
           });
     };
-    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",
-            },
-          };
-        },
-      });
-      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),
     };
   } catch (error) {
     if (exactReturnUrl) return { redirectTo: exactReturnUrl, exactReturn: true };
+    // Reading the state is the first step, so no state means the link itself
+    // was unusable: say whether it expired rather than blame configuration.
+    const failure = state ? null : oauthStateFailureReturn(deps.settings, input.state);
     return {
       redirectTo: returnUrl(
         returnBaseUrl,
-        state?.returnPath ?? "/integrations",
+        state?.returnPath ?? failure!.returnPath,
         "error",
-        errorReason(error),
+        failure?.reason ?? errorReason(error),
       ),
     };
   }
@@ -409,8 +441,13 @@ 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;
+  },
 ) {
+  assertNativeAtlassianAvailable();
   const connection = await getConnectionMetadata(
     deps.db,
     input.workspaceId,
@@ -450,7 +487,7 @@ export async function browseAtlassianSources(
 
 export async function searchAtlassianLive(
   deps: ApiRouteDeps,
-  input: {
+  input: AtlassianRequestAuthority & {
     workspaceId: string;
     subjectId: string;
     connectionId: string;
@@ -459,6 +496,7 @@ export async function searchAtlassianLive(
     limit: number;
   },
 ) {
+  assertNativeAtlassianAvailable();
   const connection = await getConnectionMetadata(
     deps.db,
     input.workspaceId,
@@ -553,7 +591,7 @@ export async function searchAtlassianLive(
 
 export async function getAtlassianLiveItem(
   deps: ApiRouteDeps,
-  input: {
+  input: AtlassianRequestAuthority & {
     workspaceId: string;
     subjectId: string;
     connectionId: string;
@@ -561,6 +599,7 @@ export async function getAtlassianLiveItem(
     id: string;
   },
 ) {
+  assertNativeAtlassianAvailable();
   const connection = await getConnectionMetadata(
     deps.db,
     input.workspaceId,
@@ -674,6 +713,7 @@ export async function saveAtlassianSources(
     canManagePersonalDestination: boolean;
   },
 ) {
+  assertNativeAtlassianAvailable();
   const parsed = SaveAtlassianSourcesRequest.safeParse(input.payload);
   if (!parsed.success) {
     throw new HTTPException(400, { message: "invalid Atlassian source selection" });
@@ -705,9 +745,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 +783,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,
@@ -765,6 +835,7 @@ export async function transitionAtlassianLifecycle(
     payload: AtlassianLifecycleActionRequest;
   },
 ) {
+  if (input.payload.action === "resume") assertNativeAtlassianAvailable();
   const connection = await getConnectionMetadata(
     deps.db,
     input.workspaceId,
@@ -783,14 +854,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 +1248,6 @@ async function materializeSchedules(
           action: { kind: "agent_turn" },
           runMode: "new_session_per_run",
           targetSessionId: null,
-          connectionAuthorities: [],
           agentConfig: knowledgeSourceAgentConfig(action),
           variableSetId: null,
           environmentId: null,
@@ -1229,7 +1312,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 +1362,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 +1424,7 @@ export function confluenceNextUrl(cloudId: string, next: string): URL {
 
 async function atlassianApiRequest(
   deps: ApiRouteDeps,
-  input: {
+  input: AtlassianRequestAuthority & {
     workspaceId: string;
     subjectId: string;
     connectionId: string;
@@ -1341,6 +1432,7 @@ async function atlassianApiRequest(
     label: string;
   },
 ): Promise<unknown> {
+  assertNativeAtlassianAvailable();
   const current = await getConnectionMetadata(
     deps.db,
     input.workspaceId,
@@ -1354,9 +1446,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,
@@ -1707,11 +1810,17 @@ function returnUrl(base: string, path: string, status: "connected" | "error", va
 }
 
 function errorReason(error: unknown): string {
+  if (error instanceof HTTPException && error.status === 410)
+    return ATLASSIAN_NATIVE_RETIRED_REASON;
   if (error instanceof AtlassianCallbackError) return error.reason;
   if (error instanceof HTTPException) return `http_${error.status}`;
   return "connection_failed";
 }
 
+function assertNativeAtlassianAvailable(): void {
+  throw new HTTPException(410, { message: ATLASSIAN_NATIVE_RETIRED_MESSAGE });
+}
+
 class AtlassianCallbackError extends Error {
   constructor(readonly reason: string) {
     super(reason);
@@ -1763,7 +1872,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 +1910,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,
@@ -45,8 +46,10 @@ import { readResponseJsonBounded, type FetchLike } from "@opengeni/network";
 import { HTTPException } from "hono/http-exception";
 import {
   integrationBaseUrl,
+  oauthStateFailureReturn,
   oauthStateTtlMs,
   requireIntegrationsStateSecret,
+  workspaceIntegrationsPath,
 } from "./oauth-client";
 
 const FIKEN_API_BASE = "https://api.fiken.no/api/v2";
@@ -63,7 +66,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 +76,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 +1108,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)
@@ -1118,7 +1125,7 @@ export async function startFikenOAuth(
     workspaceId: input.workspaceId,
     subjectId: input.subjectId,
     returnPath: safeReturnPath(
-      input.payload.returnPath ?? `/workspaces/${input.workspaceId}/capabilities`,
+      input.payload.returnPath ?? workspaceIntegrationsPath(input.workspaceId),
     ),
     ...(input.connectAttemptId ? { connectAttemptId: input.connectAttemptId } : {}),
     ...(input.externalContinuation
@@ -1168,12 +1175,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 +1230,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 +1317,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");
     }
@@ -1341,12 +1365,16 @@ export async function completeFikenOAuthCallback(
     };
   } catch (error) {
     if (exactReturnUrl) return { redirectTo: exactReturnUrl, exactReturn: true };
+    // Reading the state is the first step, so no state means the link itself
+    // was unusable: say whether it expired instead of suggesting a token.
+    const failure = state ? null : oauthStateFailureReturn(deps.settings, input.state);
     return {
       redirectTo: fikenReturnUrl(
         returnBaseUrl,
-        state?.returnPath ?? "/integrations",
+        state?.returnPath ?? failure!.returnPath,
         "error",
-        error instanceof FikenOAuthCallbackError ? error.reason : "callback_failed",
+        failure?.reason ??
+          (error instanceof FikenOAuthCallbackError ? error.reason : "callback_failed"),
       ),
     };
   }