@opengeni/api-router 0.30.3 → 1.0.0

package/src/integrations/atlassian.ts

@@ -1,4 +1,26 @@
+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";
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
+import { requireConnectOwnerAuthority } from "./connect-authority";
 import type { AccessGrant, ScheduledTask, ScheduledTaskScheduleSpec } from "@opengeni/contracts";
 import {
   ATLASSIAN_CREDENTIAL_LABEL,
@@ -24,7 +46,6 @@ import {
 import {
   captureScheduledTaskRestoreState,
   createValidatedScheduledTask,
-  hasPermission,
   manualScheduledTaskTriggerWorkflowId,
   requireEnvironmentEncryption,
   syncCreatedScheduledTask,
@@ -37,6 +58,10 @@ import {
   ConnectionDisconnectGenerationError,
   ConnectionDisconnectIdempotencyError,
   consumeIntegrationOAuthStateNonce,
+  finishConnectOperation,
+  getConnectAttempt,
+  decryptEnvironmentValue,
+  type Database,
   createConnection,
   deauthorizeKnowledgeSourceRetrieval,
   disconnectConnectionIdempotently,
@@ -44,7 +69,6 @@ import {
   getConnectionMetadata,
   getKnowledgeSourceByExternalIdentityForSyncAuthority,
   getKnowledgeSourceForSyncAuthority,
-  getWorkspaceGrant,
   listKnowledgeSourceSyncTasksForConnection,
   loadConnectionCredentialForBroker,
   recordKnowledgeLifecycleEvent,
@@ -53,17 +77,36 @@ import {
   updateScheduledTask,
   upsertKnowledgeProvider,
   upsertKnowledgeSource,
+  withWorkspaceSubjectRls,
 } from "@opengeni/db";
 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,
+  personalOwnerVerifiedInState,
+  PERSONAL_OWNER_VERIFIED_STATE_CLAIM,
+} from "../connection-ownership";
 import {
   integrationBaseUrl,
+  oauthStateFailureReturn,
   oauthStateTtlMs,
   requireIntegrationsStateSecret,
 } from "./oauth-client";
 
+/**
+ * Flow discriminator for this connector's signed OAuth state. See the matching
+ * constant in `google-drive.ts`: this state carries no `ownership` field and no
+ * provider identity, and its return path is byte-identical to one the MCP OAuth
+ * start signs from caller input, so the flow kind is what binds a state here.
+ */
+const ATLASSIAN_OAUTH_STATE_KIND = "atlassian_oauth";
 const ATLASSIAN_AUTHORIZATION_URL = "https://auth.atlassian.com/authorize";
 const ATLASSIAN_TOKEN_URL = "https://auth.atlassian.com/oauth/token";
 const ATLASSIAN_RESOURCES_URL = "https://api.atlassian.com/oauth/token/accessible-resources";
@@ -73,9 +116,13 @@ const ATLASSIAN_REQUEST_TIMEOUT_MS = 15_000;
 const ATLASSIAN_RETURN_PATH = (workspaceId: string) => `/workspaces/${workspaceId}/capabilities`;
 
 type AtlassianOAuthState = {
+  connectAttemptId?: string;
+  externalContinuation?: ExternalActorContinuation;
   accountId: string;
   workspaceId: string;
   subjectId: string;
+  /** Signed proof that a live managed human started this personal-only flow. */
+  personalOwnerVerified: boolean;
   returnPath: string;
   connectionId?: string;
   connectionVersion?: number;
@@ -99,8 +146,12 @@ export async function startAtlassianOAuth(
     subjectId: string;
     requestUrl: string;
     payload: AtlassianOAuthStartRequest;
+    connectAttemptId?: string;
+    externalContinuation?: ExternalActorContinuation;
   },
 ): Promise<AtlassianOAuthStartResponse> {
+  assertNativeAtlassianAvailable();
+  await withOrganizationIntegrationAcquisition(deps.db, input, ["atlassian"], async () => {});
   const oauth = requireAtlassianSettings(deps.settings);
   const existing = input.payload.connectionId
     ? await getConnectionMetadata(
@@ -121,6 +172,19 @@ export async function startAtlassianOAuth(
     accountId: input.accountId,
     workspaceId: input.workspaceId,
     subjectId: input.subjectId,
+    kind: ATLASSIAN_OAUTH_STATE_KIND,
+    ...(input.connectAttemptId ? { connectAttemptId: input.connectAttemptId } : {}),
+    ...(input.externalContinuation
+      ? {
+          encryptedExternalContinuation: encryptEnvironmentValue(
+            requireEnvironmentEncryption(deps.settings),
+            JSON.stringify(ExternalActorContinuation.parse(input.externalContinuation)),
+          ),
+        }
+      : {}),
+    // The route admits only a managed human, so reaching here is the proof; the
+    // callback has no live principal and enforces exactly this claim.
+    [PERSONAL_OWNER_VERIFIED_STATE_CLAIM]: true,
     returnPath: ATLASSIAN_RETURN_PATH(input.workspaceId),
     ...(existing ? { connectionId: existing.id, connectionVersion: existing.version } : {}),
   });
@@ -146,12 +210,39 @@ export async function completeAtlassianOAuthCallback(
     error?: string | undefined;
     requestUrl: string;
   },
-): Promise<{ redirectTo: string }> {
+): Promise<{ redirectTo: string; exactReturn?: boolean }> {
   const baseUrl = integrationBaseUrl(deps.settings.publicBaseUrl, input.requestUrl);
   const returnBaseUrl = deps.settings.webBaseUrl?.replace(/\/+$/, "") ?? baseUrl;
   let state: AtlassianOAuthState | null = null;
+  let exactReturnUrl: string | undefined;
+  let operation: { attemptId: string; operationId: string; inputDigest: string } | undefined;
   try {
     state = readAtlassianOAuthState(input.state, deps.settings);
+    if (state.connectAttemptId) {
+      const stored = await getConnectAttempt(deps.db, state, state.connectAttemptId);
+      if (stored.attempt.providerId !== "atlassian" || stored.attempt.ownership !== "personal")
+        throw new AtlassianCallbackError("connection_conflict");
+      exactReturnUrl = stored.returnUrl;
+      operation = {
+        attemptId: state.connectAttemptId,
+        operationId: `oauth:${state.nonce}`,
+        inputDigest: createHash("sha256").update(input.state!).digest("hex"),
+      };
+      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);
     const consumed = await consumeIntegrationOAuthStateNonce(deps.db, {
       accountId: state.accountId,
@@ -161,9 +252,52 @@ 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,
+        authorize: (tx, _attempt, origin) =>
+          requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+        commit: async (_tx, current) => ({
+          ...current,
+          revision: current.revision + 1,
+          state: input.error === "access_denied" ? "cancelled" : "failed",
+          nextAction: { type: "none" },
+          error: {
+            code: input.error ? "provider_denied" : "missing_code",
+            message: "Authorization was not completed. Start a new connection attempt.",
+            retryable: false,
+          },
+        }),
+      });
+      return { redirectTo: exactReturnUrl!, exactReturn: true };
+    }
     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`;
@@ -242,45 +376,64 @@ export async function completeAtlassianOAuthCallback(
         : {}),
       selectedSources: previousMetadata?.selectedSources ?? [],
     });
-    const connection = existing
-      ? await updateConnection(deps.db, {
-          workspaceId: state.workspaceId,
-          connectionId: existing.id,
-          visibleToSubjectId: state.subjectId,
-          expectedVersion: existing.version,
-          subjectId: state.subjectId,
-          providerDomain: ATLASSIAN_PROVIDER_DOMAIN,
-          kind: "oauth2",
-          status: "active",
-          credentialEncrypted,
-          grantedScopes: token.scopes,
-          expiresAt: token.expiresAt,
-          metadata,
-          updatedBySubjectId: state.subjectId,
-        })
-      : await createConnection(deps.db, {
-          accountId: state.accountId,
-          workspaceId: state.workspaceId,
-          subjectId: state.subjectId,
-          providerDomain: ATLASSIAN_PROVIDER_DOMAIN,
-          kind: "oauth2",
-          credentialEncrypted,
-          grantedScopes: token.scopes,
-          expiresAt: token.expiresAt,
-          metadata,
-          createdBySubjectId: state.subjectId,
-        });
+    const acceptedState = state;
+    const persist = (tx: Database) => {
+      // Capture the validated immutable callback state for delayed persistence.
+      // eslint-disable-next-line no-shadow
+      const state = acceptedState;
+      return existing
+        ? updateConnection(tx, {
+            workspaceId: state.workspaceId,
+            connectionId: existing.id,
+            visibleToSubjectId: state.subjectId,
+            expectedVersion: existing.version,
+            subjectId: state.subjectId,
+            providerDomain: ATLASSIAN_PROVIDER_DOMAIN,
+            kind: "oauth2",
+            status: "active",
+            credentialEncrypted,
+            grantedScopes: token.scopes,
+            expiresAt: token.expiresAt,
+            metadata,
+            updatedBySubjectId: state.subjectId,
+          })
+        : createConnection(tx, {
+            accountId: state.accountId,
+            workspaceId: state.workspaceId,
+            subjectId: state.subjectId,
+            providerDomain: ATLASSIAN_PROVIDER_DOMAIN,
+            kind: "oauth2",
+            credentialEncrypted,
+            grantedScopes: token.scopes,
+            expiresAt: token.expiresAt,
+            metadata,
+            createdBySubjectId: state.subjectId,
+          });
+    };
+    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),
       ),
     };
   }
@@ -288,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,
@@ -329,7 +487,7 @@ export async function browseAtlassianSources(
 
 export async function searchAtlassianLive(
   deps: ApiRouteDeps,
-  input: {
+  input: AtlassianRequestAuthority & {
     workspaceId: string;
     subjectId: string;
     connectionId: string;
@@ -338,6 +496,7 @@ export async function searchAtlassianLive(
     limit: number;
   },
 ) {
+  assertNativeAtlassianAvailable();
   const connection = await getConnectionMetadata(
     deps.db,
     input.workspaceId,
@@ -432,7 +591,7 @@ export async function searchAtlassianLive(
 
 export async function getAtlassianLiveItem(
   deps: ApiRouteDeps,
-  input: {
+  input: AtlassianRequestAuthority & {
     workspaceId: string;
     subjectId: string;
     connectionId: string;
@@ -440,6 +599,7 @@ export async function getAtlassianLiveItem(
     id: string;
   },
 ) {
+  assertNativeAtlassianAvailable();
   const connection = await getConnectionMetadata(
     deps.db,
     input.workspaceId,
@@ -553,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" });
@@ -584,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 ||
@@ -603,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,
@@ -644,6 +835,7 @@ export async function transitionAtlassianLifecycle(
     payload: AtlassianLifecycleActionRequest;
   },
 ) {
+  if (input.payload.action === "resume") assertNativeAtlassianAvailable();
   const connection = await getConnectionMetadata(
     deps.db,
     input.workspaceId,
@@ -662,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;
@@ -719,15 +924,15 @@ export async function disconnectAtlassian(
   }
 }
 
-export async function revokeAtlassianScheduleAuthorization(
+export async function preflightAtlassianScheduleAuthorization(
   deps: ApiRouteDeps,
   input: { task: ScheduledTask; subjectId: string },
 ): Promise<void> {
   const { task } = input;
-  if (task.action.kind !== "knowledge_source_sync") return;
+  if (!scheduledTaskKnowledgeSource(task)) return;
   if (
-    task.action.initiatingSubjectId !== input.subjectId ||
-    task.action.connection.ownerSubjectId !== input.subjectId
+    requireScheduledTaskKnowledgeSource(task).initiatingSubjectId !== input.subjectId ||
+    requireScheduledTaskKnowledgeSource(task).connection.ownerSubjectId !== input.subjectId
   ) {
     throw new HTTPException(403, {
       message: "knowledge source schedule requires the exact initiating subject",
@@ -737,50 +942,118 @@ export async function revokeAtlassianScheduleAuthorization(
   if (!externalSourceId) {
     throw new HTTPException(409, { message: "Atlassian schedule identity is incomplete" });
   }
-  const connection = await getConnectionMetadata(
-    deps.db,
-    task.workspaceId,
-    task.action.connection.connectionId,
-    input.subjectId,
-  );
-  if (!connection) throw new HTTPException(409, { message: "Atlassian connection is unavailable" });
-  const metadata = requireAtlassianConnection(connection, input.subjectId);
-  const selected = metadata.selectedSources.find((source) => source.id === externalSourceId);
-  let authorityVersion = connection.version;
-  if (selected?.syncEnabled) {
-    const updated = await transitionConnectionState(deps.db, {
-      workspaceId: task.workspaceId,
-      connectionId: connection.id,
-      visibleToSubjectId: input.subjectId,
-      expectedVersion: connection.version,
-      metadata: AtlassianConnectionMetadata.parse({
-        ...metadata,
-        selectedSources: metadata.selectedSources.map((source) =>
-          source.id === externalSourceId
-            ? { ...source, syncEnabled: false, configGeneration: source.configGeneration + 1 }
-            : source,
-        ),
-      }),
-      updatedBySubjectId: input.subjectId,
+  // Current connector attachment is not deletion authority. The frozen task
+  // revision and generation-fenced cleanup descriptor are.
+}
+
+export async function revokeAtlassianScheduleAuthorization(
+  deps: ApiRouteDeps,
+  input: { task: ScheduledTask; subjectId: string },
+): Promise<void> {
+  const { task } = input;
+  if (!scheduledTaskKnowledgeSource(task)) return;
+  if (
+    requireScheduledTaskKnowledgeSource(task).initiatingSubjectId !== input.subjectId ||
+    requireScheduledTaskKnowledgeSource(task).connection.ownerSubjectId !== input.subjectId
+  ) {
+    throw new HTTPException(403, {
+      message: "knowledge source schedule requires the exact initiating subject",
     });
-    if (!updated) throw new HTTPException(409, { message: "Atlassian connection changed" });
-    authorityVersion = updated.version;
   }
-  const resolved = await getKnowledgeSourceForSyncAuthority(deps.db, {
+  const externalSourceId = optionalString(task.metadata.externalSourceId);
+  if (!externalSourceId) {
+    throw new HTTPException(409, { message: "Atlassian schedule identity is incomplete" });
+  }
+  await cleanupAtlassianScheduleAuthorization(deps, {
+    taskId: task.id,
     accountId: task.accountId,
     workspaceId: task.workspaceId,
-    sourceId: task.action.sourceId,
+    connectionId: requireScheduledTaskKnowledgeSource(task).connection.connectionId,
+    connectionVersion: requireScheduledTaskKnowledgeSource(task).connection.connectionVersion,
+    sourceId: requireScheduledTaskKnowledgeSource(task).sourceId,
+    sourceLifecycleGeneration: requireScheduledTaskKnowledgeSource(task).sourceLifecycleGeneration,
+    sourceConfigGeneration: requireScheduledTaskKnowledgeSource(task).sourceConfigGeneration,
+    externalSourceId,
+    subjectId: input.subjectId,
+  });
+}
+
+export async function cleanupAtlassianScheduleAuthorization(
+  deps: ApiRouteDeps,
+  input: {
+    taskId: string;
+    accountId: string;
+    workspaceId: string;
+    connectionId: string;
+    connectionVersion: number;
+    sourceId: string;
+    sourceLifecycleGeneration: number;
+    sourceConfigGeneration: number;
+    externalSourceId: string;
+    subjectId: string;
+  },
+): Promise<void> {
+  const resolvedBeforeLock = await getKnowledgeSourceForSyncAuthority(deps.db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    sourceId: input.sourceId,
     initiatingSubjectId: input.subjectId,
   });
-  if (resolved?.source.lifecycleState === "active") {
-    await recordKnowledgeLifecycleEvent(deps.db, {
-      accountId: task.accountId,
-      workspaceId: task.workspaceId,
+  if (
+    resolvedBeforeLock?.source.lifecycleState !== "active" ||
+    resolvedBeforeLock.source.lifecycleGeneration !== input.sourceLifecycleGeneration
+  ) {
+    return;
+  }
+  await withWorkspaceSubjectRls(deps.db, input.workspaceId, input.subjectId, async (tx) => {
+    const connection = await getConnectionMetadata(
+      tx,
+      input.workspaceId,
+      input.connectionId,
+      input.subjectId,
+    );
+    let authorityVersion = input.connectionVersion;
+    if (connection) {
+      const metadata = requireAtlassianConnection(connection, input.subjectId);
+      authorityVersion = connection.version;
+      const updated = await transitionConnectionState(tx, {
+        workspaceId: input.workspaceId,
+        connectionId: connection.id,
+        visibleToSubjectId: input.subjectId,
+        expectedVersion: connection.version,
+        metadata: AtlassianConnectionMetadata.parse({
+          ...metadata,
+          selectedSources: metadata.selectedSources.map((source) =>
+            source.id === input.externalSourceId
+              ? { ...source, syncEnabled: false, configGeneration: source.configGeneration + 1 }
+              : source,
+          ),
+        }),
+        updatedBySubjectId: input.subjectId,
+      });
+      if (!updated) throw new HTTPException(409, { message: "Atlassian connection changed" });
+      authorityVersion = updated.version;
+    }
+    const resolved = await getKnowledgeSourceForSyncAuthority(tx, {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      sourceId: input.sourceId,
+      initiatingSubjectId: input.subjectId,
+    });
+    if (
+      resolved?.source.lifecycleState !== "active" ||
+      resolved.source.lifecycleGeneration !== input.sourceLifecycleGeneration
+    ) {
+      throw new HTTPException(409, { message: "Atlassian knowledge source changed" });
+    }
+    await recordKnowledgeLifecycleEvent(tx, {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
       targetKind: "source",
       targetId: resolved.source.id,
       eventType: "deleted",
       expectedGeneration: resolved.source.lifecycleGeneration,
-      operationId: `atlassian-schedule-delete:${task.id}:${authorityVersion}`,
+      operationId: `atlassian-schedule-delete:${input.taskId}:${authorityVersion}`,
       reasonCode: "schedule_deleted",
       actor: {
         kind: "human",
@@ -788,7 +1061,7 @@ export async function revokeAtlassianScheduleAuthorization(
         initiatingHumanSubjectId: input.subjectId,
       },
     });
-  }
+  });
 }
 
 async function materializeSchedules(
@@ -830,11 +1103,11 @@ async function materializeSchedules(
     let source = null as Awaited<ReturnType<typeof upsertKnowledgeSource>> | null;
     let existingTask: (typeof tasks)[number] | null = null;
     for (const task of tasks) {
-      if (task.action.kind !== "knowledge_source_sync") continue;
+      if (!scheduledTaskKnowledgeSource(task)) continue;
       const resolved = await getKnowledgeSourceForSyncAuthority(deps.db, {
         accountId: input.accountId,
         workspaceId: input.workspaceId,
-        sourceId: task.action.sourceId,
+        sourceId: requireScheduledTaskKnowledgeSource(task).sourceId,
         initiatingSubjectId: input.subjectId,
       });
       if (resolved?.source.externalSourceId !== identity.externalSourceId) continue;
@@ -941,7 +1214,10 @@ async function materializeSchedules(
         name: `Sync ${selectedSource.kind === "jira_project" ? "Jira" : "Confluence"}: ${selectedSource.name}`,
         schedule: atlassianSchedule(selectedSource.syncCadence),
         overlapPolicy: "buffer_one",
-        action,
+        action: { kind: "agent_turn" },
+        agentConfig: knowledgeSourceAgentConfig(action, existingTask.agentConfig),
+        refreshPersonalResourceAuthority: true,
+        authorityUpdatedBy: { kind: "subject", subjectId: input.subjectId },
         metadata: {
           ...existingTask.metadata,
           connectorKind: "atlassian",
@@ -969,15 +1245,11 @@ async function materializeSchedules(
           status: "active",
           schedule: atlassianSchedule(selectedSource.syncCadence),
           overlapPolicy: "buffer_one",
-          action,
+          action: { kind: "agent_turn" },
           runMode: "new_session_per_run",
           targetSessionId: null,
-          agentConfig: {
-            prompt: "Knowledge source synchronization",
-            resources: [],
-            tools: [],
-            metadata: {},
-          },
+          connectionAccounts: [],
+          agentConfig: knowledgeSourceAgentConfig(action),
           variableSetId: null,
           environmentId: null,
           rigId: null,
@@ -1002,11 +1274,11 @@ async function materializeSchedules(
   }
 
   for (const task of tasks) {
-    if (task.action.kind !== "knowledge_source_sync") continue;
+    if (!scheduledTaskKnowledgeSource(task)) continue;
     const resolved = await getKnowledgeSourceForSyncAuthority(deps.db, {
       accountId: input.accountId,
       workspaceId: input.workspaceId,
-      sourceId: task.action.sourceId,
+      sourceId: requireScheduledTaskKnowledgeSource(task).sourceId,
       initiatingSubjectId: input.subjectId,
     });
     if (!resolved || enabledIds.has(resolved.source.externalSourceId)) continue;
@@ -1041,7 +1313,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[] = [];
@@ -1087,7 +1363,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[] = [];
@@ -1145,7 +1425,7 @@ export function confluenceNextUrl(cloudId: string, next: string): URL {
 
 async function atlassianApiRequest(
   deps: ApiRouteDeps,
-  input: {
+  input: AtlassianRequestAuthority & {
     workspaceId: string;
     subjectId: string;
     connectionId: string;
@@ -1153,6 +1433,7 @@ async function atlassianApiRequest(
     label: string;
   },
 ): Promise<unknown> {
+  assertNativeAtlassianAvailable();
   const current = await getConnectionMetadata(
     deps.db,
     input.workspaceId,
@@ -1166,9 +1447,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,
@@ -1325,20 +1617,20 @@ async function deauthorizeConnectionSources(
     connection.id,
   );
   for (const task of tasks) {
-    if (task.action.kind !== "knowledge_source_sync") continue;
+    if (!scheduledTaskKnowledgeSource(task)) continue;
     const resolved = await getKnowledgeSourceForSyncAuthority(deps.db, {
       accountId: task.accountId,
       workspaceId: task.workspaceId,
-      sourceId: task.action.sourceId,
+      sourceId: requireScheduledTaskKnowledgeSource(task).sourceId,
       initiatingSubjectId: subjectId,
     });
     if (!resolved || resolved.source.lifecycleState !== "active") continue;
     await deauthorizeKnowledgeSourceRetrieval(deps.db, {
       accountId: task.accountId,
       workspaceId: task.workspaceId,
-      sourceId: task.action.sourceId,
-      audience: task.action.destination,
-      operationId: `atlassian-deauthorize:${connection.id}:${connection.version + 1}:${task.action.sourceId}:${reasonCode}`,
+      sourceId: requireScheduledTaskKnowledgeSource(task).sourceId,
+      audience: requireScheduledTaskKnowledgeSource(task).destination,
+      operationId: `atlassian-deauthorize:${connection.id}:${connection.version + 1}:${requireScheduledTaskKnowledgeSource(task).sourceId}:${reasonCode}`,
       reasonCode,
       actor: { kind: "human", subjectId, initiatingHumanSubjectId: subjectId },
     });
@@ -1409,6 +1701,12 @@ function readAtlassianOAuthState(raw: string | undefined, settings: Settings): A
   if (iat === undefined || now < iat || now - iat > oauthStateTtlMs / 1_000) {
     throw new HTTPException(400, { message: "expired Atlassian OAuth state" });
   }
+  // Reject a state minted by any other flow before reading anything else. A
+  // pre-cutover state carries no kind and is refused; that is the same bounded
+  // `oauthStateTtlMs` window the personal-owner claim already fails closed on.
+  if (payload.kind !== ATLASSIAN_OAUTH_STATE_KIND) {
+    throw new HTTPException(400, { message: "invalid Atlassian OAuth state" });
+  }
   const accountId = requiredString(payload.accountId, "state.accountId");
   const workspaceId = requiredString(payload.workspaceId, "state.workspaceId");
   const subjectId = requiredString(payload.subjectId, "state.subjectId");
@@ -1425,6 +1723,22 @@ function readAtlassianOAuthState(raw: string | undefined, settings: Settings): A
     accountId,
     workspaceId,
     subjectId,
+    personalOwnerVerified: personalOwnerVerifiedInState(payload),
+    ...(typeof payload.connectAttemptId === "string"
+      ? { connectAttemptId: payload.connectAttemptId }
+      : {}),
+    ...(typeof payload.encryptedExternalContinuation === "string"
+      ? {
+          externalContinuation: ExternalActorContinuation.parse(
+            JSON.parse(
+              decryptEnvironmentValue(
+                requireEnvironmentEncryption(settings),
+                payload.encryptedExternalContinuation,
+              ),
+            ),
+          ),
+        }
+      : {}),
     returnPath,
     ...(connectionId ? { connectionId, connectionVersion: connectionVersion! } : {}),
     nonce: requiredString(payload.nonce, "state.nonce"),
@@ -1433,14 +1747,22 @@ function readAtlassianOAuthState(raw: string | undefined, settings: Settings): A
 }
 
 async function requireCallbackGrant(deps: ApiRouteDeps, state: AtlassianOAuthState): Promise<void> {
-  const grant = await getWorkspaceGrant(deps.db, state.subjectId, state.workspaceId);
+  // This connector is personal-only by construction: its start request carries
+  // no ownership and the callback always writes `subjectId: state.subjectId`.
+  // A state minted before the start-side principal fence existed carries no
+  // `personalOwnerVerified` claim and must not land a personal Connection.
   if (
-    !grant ||
-    grant.accountId !== state.accountId ||
-    !hasPermission(grant.permissions, "connections:write")
+    !personalOwnerStateAccepted({
+      ownership: "personal",
+      subjectId: state.subjectId,
+      personalOwnerVerified: state.personalOwnerVerified,
+    })
   ) {
-    throw new HTTPException(403, { message: "Atlassian OAuth subject no longer has access" });
+    throw new HTTPException(422, {
+      message: personalOnlyConnectionPrincipalMessage("Atlassian"),
+    });
   }
+  await requireConnectOwnerAuthority(deps.db, state, "connections:write");
 }
 
 function requireAtlassianSettings(settings: Settings) {
@@ -1489,11 +1811,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);
@@ -1545,7 +1873,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 }> = [];
@@ -1578,7 +1911,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 }> = [];