@opengeni/api-router 3.0.1 → 3.1.2

package/src/integrations/google-drive.ts

@@ -1,7 +1,17 @@
+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 { createHash, randomBytes } from "node:crypto";
 import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
@@ -48,6 +58,7 @@ import {
 } from "@opengeni/contracts";
 import {
   GOOGLE_DRIVE_INTEGRATION_DEFINITION,
+  CORE_INTEGRATION_DEFINITIONS,
   integrationDefinitionProviderDomain,
 } from "@opengeni/capabilities";
 import {
@@ -68,10 +79,10 @@ import {
   ConnectionDisconnectGenerationError,
   ConnectionDisconnectIdempotencyError,
   consumeIntegrationOAuthStateNonce,
-  claimConnectOperation,
   finishConnectOperation,
   getConnectAttempt,
   type Database,
+  listInstalledApiIntegrations,
   createConnection,
   decryptEnvironmentValue,
   disconnectConnectionIdempotently,
@@ -105,6 +116,7 @@ import {
 } from "../connection-ownership";
 import {
   integrationBaseUrl,
+  oauthStateFailureReturn,
   oauthStateTtlMs,
   requireIntegrationsStateSecret,
 } from "./oauth-client";
@@ -146,6 +158,8 @@ type GoogleDriveOAuthState = {
   returnPath: string;
   encryptedPkceVerifier: string;
   capability: "source_read" | "publish";
+  /** Server-verified Picker selection, carried only into the scope-upgrade step. */
+  publishingFolderId?: string;
   connectionId?: string;
   connectionVersion?: number;
   nonce: string;
@@ -254,7 +268,8 @@ export async function startGoogleDriveOAuth(
     externalContinuation?: ExternalActorContinuation;
   },
 ): Promise<GoogleDriveOAuthStartResponse> {
-  const google = requireGoogleDriveSettings(deps.settings);
+  await withOrganizationIntegrationAcquisition(deps.db, input, ["google-drive"], async () => {});
+  requireGoogleDriveSettings(deps.settings);
   const existing = input.payload.connectionId
     ? await getConnectionMetadata(
         deps.db,
@@ -275,46 +290,64 @@ export async function startGoogleDriveOAuth(
     requireGoogleDriveConnection(existing, input.subjectId);
   }
 
-  const key = requireEnvironmentEncryption(deps.settings);
-  const verifier = randomBytes(48).toString("base64url");
-  const redirectUri = requireGoogleDriveOAuthCallbackUrl(deps.settings);
-  const state = createSignedState(requireIntegrationsStateSecret(deps.settings), {
+  return googleDriveOAuthAuthorization(deps.settings, {
     accountId: input.accountId,
     workspaceId: input.workspaceId,
     subjectId: input.subjectId,
-    kind: GOOGLE_DRIVE_OAUTH_STATE_KIND,
     ...(input.connectAttemptId ? { connectAttemptId: input.connectAttemptId } : {}),
-    ...(input.externalContinuation
+    ...(input.externalContinuation ? { externalContinuation: 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: GOOGLE_DRIVE_RETURN_PATH(input.workspaceId),
+    capability: input.payload.capability,
+    ...(existing ? { connectionId: existing.id, connectionVersion: existing.version } : {}),
+  });
+}
+
+function googleDriveOAuthAuthorization(
+  settings: Settings,
+  authority: Omit<GoogleDriveOAuthState, "nonce" | "iat" | "encryptedPkceVerifier">,
+): GoogleDriveOAuthStartResponse {
+  const key = requireEnvironmentEncryption(settings);
+  const verifier = randomBytes(48).toString("base64url");
+  const { externalContinuation, ...claims } = authority;
+  const state = createSignedState(requireIntegrationsStateSecret(settings), {
+    ...claims,
+    kind: GOOGLE_DRIVE_OAUTH_STATE_KIND,
+    ...(externalContinuation
       ? {
           encryptedExternalContinuation: encryptEnvironmentValue(
             key,
-            JSON.stringify(ExternalActorContinuation.parse(input.externalContinuation)),
+            JSON.stringify(ExternalActorContinuation.parse(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: GOOGLE_DRIVE_RETURN_PATH(input.workspaceId),
     encryptedPkceVerifier: encryptEnvironmentValue(key, verifier),
-    capability: input.payload.capability,
-    ...(existing ? { connectionId: existing.id, connectionVersion: existing.version } : {}),
   });
+  const pickingFolder = authority.capability === "publish" && !authority.publishingFolderId;
   const authorizationUrl = new URL(GOOGLE_AUTHORIZATION_URL);
-  authorizationUrl.searchParams.set("client_id", google.clientId);
-  authorizationUrl.searchParams.set("redirect_uri", redirectUri);
+  authorizationUrl.searchParams.set("client_id", requireGoogleDriveSettings(settings).clientId);
+  authorizationUrl.searchParams.set("redirect_uri", requireGoogleDriveOAuthCallbackUrl(settings));
   authorizationUrl.searchParams.set("response_type", "code");
   authorizationUrl.searchParams.set(
     "scope",
-    input.payload.capability === "publish" ? GOOGLE_DRIVE_FILE_SCOPE : GOOGLE_DRIVE_READONLY_SCOPE,
+    pickingFolder
+      ? GOOGLE_DRIVE_FILE_SCOPE
+      : authority.capability === "publish"
+        ? `${GOOGLE_DRIVE_READONLY_SCOPE} ${GOOGLE_DRIVE_FILE_SCOPE}`
+        : GOOGLE_DRIVE_READONLY_SCOPE,
   );
   authorizationUrl.searchParams.set("access_type", "offline");
-  authorizationUrl.searchParams.set("include_granted_scopes", "true");
+  // Google's OAuth-integrated Picker permits drive.file alone. Incremental
+  // authorization would import existing Drive/Gmail grants and reject it with
+  // invalid_scope. Merge grants only in a separate ordinary OAuth request.
+  authorizationUrl.searchParams.set("include_granted_scopes", pickingFolder ? "false" : "true");
   authorizationUrl.searchParams.set(
     "prompt",
-    input.payload.capability === "publish" ? "consent" : "consent select_account",
+    authority.capability === "publish" ? "consent" : "consent select_account",
   );
-  if (input.payload.capability === "publish") {
+  if (pickingFolder) {
     authorizationUrl.searchParams.set("trigger_onepick", "true");
     authorizationUrl.searchParams.set("allow_folder_selection", "true");
     authorizationUrl.searchParams.set("allow_multiple", "false");
@@ -348,6 +381,8 @@ export async function completeGoogleDriveOAuthCallback(
   let state: GoogleDriveOAuthState | null = null;
   let exactReturnUrl: string | undefined;
   let operation: { attemptId: string; operationId: string; inputDigest: string } | undefined;
+  let operationClaimed = false;
+  let operationSettlementStarted = false;
   try {
     state = readGoogleDriveOAuthState(input.state, deps.settings);
     if (state.connectAttemptId) {
@@ -364,13 +399,32 @@ export async function completeGoogleDriveOAuthCallback(
         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),
-      });
-      if (claim.status === "replayed") return { redirectTo: exactReturnUrl, exactReturn: true };
+      const claim = await claimOAuthAcquisition(
+        deps.db,
+        state,
+        {
+          ...operation,
+          expectedRevision: stored.attempt.revision,
+          authorize: (tx, _attempt, origin) =>
+            requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+        },
+        "google-drive",
+        Boolean(input.code && !input.error),
+      );
+      if (claim.status === "replayed") {
+        // A first-stage receipt retains its continuation even after final
+        // completion or cancellation. Reopen only the still-current action.
+        const latest = await getConnectAttempt(deps.db, state, state.connectAttemptId);
+        if (
+          claim.attempt.nextAction.type === "authorize" &&
+          latest.attempt.nextAction.type === "authorize" &&
+          latest.attempt.nextAction.url === claim.attempt.nextAction.url
+        ) {
+          return { redirectTo: claim.attempt.nextAction.url };
+        }
+        return { redirectTo: exactReturnUrl, exactReturn: true };
+      }
+      operationClaimed = true;
     }
     await requireGoogleDriveCallbackGrant(deps, state);
     const consumed = await consumeIntegrationOAuthStateNonce(deps.db, {
@@ -382,9 +436,10 @@ export async function completeGoogleDriveOAuthCallback(
       now: new Date(),
     });
     if (!consumed) {
-      throw new HTTPException(400, { message: "Google Drive OAuth state has already been used" });
+      throw new GoogleDriveCallbackError("state_replayed");
     }
     if (operation && (input.error || !input.code)) {
+      operationSettlementStarted = true;
       await finishConnectOperation(deps.db, state, {
         ...operation,
         authorize: (tx, _attempt, origin) =>
@@ -409,6 +464,7 @@ export async function completeGoogleDriveOAuthCallback(
     if (!input.code) {
       throw new GoogleDriveCallbackError("missing_code");
     }
+    await withOrganizationIntegrationAcquisition(deps.db, state, ["google-drive"], async () => {});
 
     const google = requireGoogleDriveSettings(deps.settings);
     const key = requireEnvironmentEncryption(deps.settings);
@@ -431,8 +487,7 @@ export async function completeGoogleDriveOAuthCallback(
     if (
       !scopeDecision.accessMode ||
       !scopeDecision.capabilities.includes(requiredCapability) ||
-      (state.capability === "publish" &&
-        !scopeDecision.capabilities.includes("recursive_source_sync"))
+      (state.publishingFolderId && !scopeDecision.capabilities.includes("recursive_source_sync"))
     ) {
       throw new GoogleDriveCallbackError("scope_not_granted");
     }
@@ -461,12 +516,43 @@ export async function completeGoogleDriveOAuthCallback(
       state.capability === "publish"
         ? await verifyPickedGoogleDriveOutputDestination(
             token.accessToken,
-            input.pickedFileIds,
+            state.publishingFolderId ?? input.pickedFileIds,
             fetchImpl,
           )
         : previousMetadata?.outputDestination;
     if (state.capability === "publish") {
       if (!existing) throw new GoogleDriveCallbackError("connection_conflict");
+      if (!state.publishingFolderId) {
+        // The file-only Picker credential must never replace the existing
+        // recursive-read credential. Carry only its verified folder into a
+        // fresh, single-use PKCE flow that obtains both capabilities.
+        const { nonce: _nonce, iat: _iat, encryptedPkceVerifier: _verifier, ...authority } = state;
+        const continuation = googleDriveOAuthAuthorization(deps.settings, {
+          ...authority,
+          publishingFolderId: outputDestination!.folderId,
+        });
+        if (operation) {
+          const acceptedState = state;
+          operationSettlementStarted = true;
+          await finishOAuthAcquisition(
+            deps.db,
+            acceptedState,
+            {
+              ...operation,
+              authorize: (tx, _attempt, origin) =>
+                requireConnectOwnerAuthority(tx, acceptedState, "connections:write", origin),
+              commit: async (_tx, current) => ({
+                ...current,
+                revision: current.revision + 1,
+                state: "requires_user_action",
+                nextAction: { type: "authorize", url: continuation.authorizationUrl },
+              }),
+            },
+            "google-drive",
+          );
+        }
+        return { redirectTo: continuation.authorizationUrl };
+      }
     }
     let refreshToken = token.refreshToken;
     if (!refreshToken && existing) {
@@ -562,36 +648,47 @@ export async function completeGoogleDriveOAuthCallback(
           });
     };
     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 GoogleDriveCallbackError("connection_conflict");
-          return {
-            ...current,
-            revision: current.revision + 1,
-            state: "complete",
-            credentialsCommitted: true,
-            nextAction: { type: "none" },
-            account: {
-              id: connection.id,
-              version: connection.version,
-              providerId: current.providerId,
-              label: identity.emailAddress ?? identity.displayName,
-              ownership: "personal",
-              status: "connected",
-            },
-          };
+      operationSettlementStarted = true;
+      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 GoogleDriveCallbackError("connection_conflict");
+            return {
+              ...current,
+              revision: current.revision + 1,
+              state: "complete",
+              credentialsCommitted: true,
+              nextAction: { type: "none" },
+              account: {
+                id: connection.id,
+                version: connection.version,
+                providerId: current.providerId,
+                label: identity.emailAddress ?? identity.displayName,
+                ownership: "personal",
+                status: "connected",
+              },
+            };
+          },
         },
-      });
+        "google-drive",
+      );
       return { redirectTo: exactReturnUrl!, exactReturn: true };
     }
-    const connection = await deps.db.transaction(async (tx) => {
-      await requireGoogleDriveCallbackGrant({ ...deps, db: tx }, acceptedState);
-      return persist(tx);
-    });
+    const connection = await withOrganizationIntegrationAcquisition(
+      deps.db,
+      acceptedState,
+      ["google-drive"],
+      async (tx) => {
+        await requireGoogleDriveCallbackGrant({ ...deps, db: tx }, acceptedState);
+        return persist(tx);
+      },
+    );
     if (!connection) {
       throw new GoogleDriveCallbackError("connection_conflict");
     }
@@ -599,13 +696,60 @@ export async function completeGoogleDriveOAuthCallback(
       redirectTo: googleDriveReturnUrl(returnBaseUrl, state.returnPath, "connected", connection.id),
     };
   } catch (error) {
+    if (
+      state &&
+      operation &&
+      operationClaimed &&
+      !operationSettlementStarted &&
+      error instanceof GoogleDriveCallbackError &&
+      [
+        "state_replayed",
+        "scope_not_granted",
+        "connection_conflict",
+        "account_mismatch",
+        "output_folder_required",
+        "output_folder_unavailable",
+        "refresh_token_missing",
+        "identity_verification_failed",
+      ].includes(error.reason)
+    ) {
+      // A definite validation rejection before persistence has no connection
+      // effect. Record a terminal receipt so polling and replay can finish.
+      // Transport failures and errors after settlement starts remain fenced:
+      // their outcome may be unknown, so never overwrite or retry them here.
+      const acceptedState = state;
+      try {
+        await finishConnectOperation(deps.db, acceptedState, {
+          ...operation,
+          authorize: (tx, _attempt, origin) =>
+            requireConnectOwnerAuthority(tx, acceptedState, "connections:write", origin),
+          commit: async (_tx, current) => ({
+            ...current,
+            revision: current.revision + 1,
+            state: "failed",
+            nextAction: { type: "none" },
+            error: {
+              code: error.reason,
+              message: "Authorization was not completed. Start a new connection attempt.",
+              retryable: false,
+            },
+          }),
+        });
+      } catch {
+        // Revoked authority or unavailable storage cannot authorize settlement.
+        // Preserve the claim rather than manufacture a terminal outcome.
+      }
+    }
     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: googleDriveReturnUrl(
         returnBaseUrl,
-        state?.returnPath ?? "/integrations",
+        state?.returnPath ?? failure!.returnPath,
         "error",
-        googleDriveErrorReason(error),
+        failure?.reason ?? googleDriveErrorReason(error),
       ),
     };
   }
@@ -682,19 +826,45 @@ export async function transitionGoogleDriveLifecycle(
     );
   }
 
-  const updated = await transitionConnectionState(deps.db, {
-    workspaceId: input.workspaceId,
-    connectionId: existing.id,
-    visibleToSubjectId: input.subjectId,
-    expectedVersion: existing.version,
-    status: "active",
-    metadata: GoogleDriveConnectionMetadata.parse({
-      ...metadata,
-      lifecycle: googleDriveLifecycle(targetState),
-    }),
-    lastError: null,
-    updatedBySubjectId: input.subjectId,
-  });
+  const persist = (tx: Database) =>
+    transitionConnectionState(tx, {
+      workspaceId: input.workspaceId,
+      connectionId: existing.id,
+      visibleToSubjectId: input.subjectId,
+      expectedVersion: existing.version,
+      status: "active",
+      metadata: GoogleDriveConnectionMetadata.parse({
+        ...metadata,
+        lifecycle: googleDriveLifecycle(targetState),
+      }),
+      lastError: null,
+      updatedBySubjectId: input.subjectId,
+    });
+  const updated =
+    input.payload.action === "resume"
+      ? await withOrganizationIntegrationPolicyFence(
+          deps.db,
+          { accountId: existing.accountId, workspaceId: input.workspaceId },
+          async (tx, policy) => {
+            const current = await getConnectionMetadata(
+              tx,
+              input.workspaceId,
+              input.connectionId,
+              input.subjectId,
+            );
+            if (
+              current?.status === "active" &&
+              effectiveGoogleDriveLifecycle(
+                current,
+                requireGoogleDriveConnection(current, input.subjectId),
+              ).state === "active"
+            )
+              return current;
+            assertOrganizationIntegrationAllowed(policy, "google-drive");
+            return persist(tx);
+          },
+        )
+      : await persist(deps.db);
   if (!updated) {
     const converged = await getConnectionMetadata(
       deps.db,
@@ -972,58 +1142,141 @@ export async function saveGoogleDriveFacetSource(
   }
   const requestedDestination = bindGoogleDriveDocumentDestination(input, payload);
   const requestedConfig = googleDriveFacetConfig(requestedSources, requestedDestination, payload);
-  const replayed = await replayCompletedIntegrationFacetOperation<IntegrationFacetMutationResult>(
+  const admitted = await withOrganizationIntegrationPolicyFence(
     deps.db,
-    {
-      accountId: input.accountId,
-      workspaceId: input.workspaceId,
-      subjectId: input.subjectId,
-      capabilityId: input.capabilityId,
-      instanceKey: input.instanceKey,
-      facetKey: input.facetKey,
-      idempotencyKey: payload.idempotencyKey,
-      kind: "configure",
-      expectedRequestDigest: (result) => {
-        const displayName = integrationFacetReceiptDisplayName(result);
-        if (displayName === null) return "invalid-integration-facet-receipt";
-        return integrationFacetConfigureRequestDigest({
+    input,
+    async (tx, policy) => {
+      const replayed =
+        await replayCompletedIntegrationFacetOperation<IntegrationFacetMutationResult>(tx, {
+          accountId: input.accountId,
+          workspaceId: input.workspaceId,
+          subjectId: input.subjectId,
           capabilityId: input.capabilityId,
           instanceKey: input.instanceKey,
           facetKey: input.facetKey,
-          displayName,
-          config: requestedConfig,
-          ...(payload.expectedVersion !== undefined
-            ? { expectedVersion: payload.expectedVersion }
-            : {}),
+          idempotencyKey: payload.idempotencyKey,
+          kind: "configure",
+          expectedRequestDigest: (result) => {
+            const displayName = integrationFacetReceiptDisplayName(result);
+            if (displayName === null) return "invalid-integration-facet-receipt";
+            return integrationFacetConfigureRequestDigest({
+              capabilityId: input.capabilityId,
+              instanceKey: input.instanceKey,
+              facetKey: input.facetKey,
+              displayName,
+              config: requestedConfig,
+              ...(payload.expectedVersion !== undefined
+                ? { expectedVersion: payload.expectedVersion }
+                : {}),
+            });
+          },
         });
-      },
+      if (replayed) return { replayed: IntegrationFacetMutationResult.parse(replayed) };
+      const context = await requireGoogleDriveIntegrationFacet({ ...deps, db: tx }, input);
+      googleDriveDocumentDestination(input, payload);
+      const acquiring = googleDriveFacetSelectionRequiresAcquisition(context, requestedConfig);
+      if (acquiring) {
+        const installed = (
+          await listInstalledApiIntegrations(tx, input.workspaceId, input.subjectId)
+        ).find(
+          (candidate) =>
+            candidate.capabilityId === input.capabilityId &&
+            candidate.instanceKey === input.instanceKey,
+        );
+        assertOrganizationIntegrationAllowed(
+          policy,
+          installed
+            ? installedGoogleDriveFacetKey({
+                apiProtocol: installed.protocol,
+                definitionId: installed.definitionId,
+                definitionProvenance: installed.definitionProvenance,
+              })
+            : null,
+        );
+      }
+      return { context, acquiring };
     },
   );
-  if (replayed) return IntegrationFacetMutationResult.parse(replayed);
-  const context = await requireGoogleDriveIntegrationFacet(deps, input);
-  googleDriveDocumentDestination(input, payload);
-  await verifyGoogleDriveSources(deps, {
-    workspaceId: input.workspaceId,
-    subjectId: input.subjectId,
-    connectionId: context.connection.id,
-    sources: requestedSources,
-  });
-  return IntegrationFacetMutationResult.parse(
-    await configureIntegrationFacet(deps.db, {
-      accountId: input.accountId,
+  if (admitted.replayed) return admitted.replayed;
+  const context = admitted.context!;
+  if (admitted.acquiring)
+    await verifyGoogleDriveSources(deps, {
       workspaceId: input.workspaceId,
       subjectId: input.subjectId,
-      capabilityId: input.capabilityId,
-      instanceKey: input.instanceKey,
-      facetKey: input.facetKey,
-      displayName:
-        context.facet.binding?.displayName ?? `${input.instanceKey} — Google Drive content`,
-      config: requestedConfig,
-      ...(payload.expectedVersion !== undefined
-        ? { expectedVersion: payload.expectedVersion }
-        : {}),
-      idempotencyKey: payload.idempotencyKey,
-    }),
+      connectionId: context.connection.id,
+      sources: requestedSources,
+    });
+  return IntegrationFacetMutationResult.parse(
+    await withOrganizationIntegrationPolicyFence(deps.db, input, (tx, policy) =>
+      configureIntegrationFacet(tx, {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        subjectId: input.subjectId,
+        capabilityId: input.capabilityId,
+        instanceKey: input.instanceKey,
+        facetKey: input.facetKey,
+        displayName:
+          context.facet.binding?.displayName ?? `${input.instanceKey} — Google Drive content`,
+        config: requestedConfig,
+        ...(payload.expectedVersion !== undefined
+          ? { expectedVersion: payload.expectedVersion }
+          : {}),
+        idempotencyKey: payload.idempotencyKey,
+        beforeAcquire: async (locked, installed) => {
+          const current = await requireGoogleDriveIntegrationFacet({ ...deps, db: locked }, input);
+          if (googleDriveFacetSelectionRequiresAcquisition(current, requestedConfig)) {
+            assertOrganizationIntegrationAllowed(policy, installedGoogleDriveFacetKey(installed));
+            if (!admitted.acquiring)
+              throw new HTTPException(409, {
+                message: "Google Drive source binding changed; verify the selection again",
+              });
+          }
+        },
+      }),
+    ),
+  );
+}
+
+/** This is installed server-authored version provenance, not a facet's mutable
+ * capabilities.provider, URL, domain, or client-authored credential metadata. */
+function installedGoogleDriveFacetKey(context: {
+  apiProtocol: string | null;
+  definitionId: string | null;
+  definitionProvenance: string | null;
+}): string | null {
+  if (context.apiProtocol !== "openapi" && context.apiProtocol !== "graphql") return null;
+  if (context.definitionProvenance === "workspace") return `custom:${context.apiProtocol}`;
+  return context.definitionProvenance === "curated" &&
+    CORE_INTEGRATION_DEFINITIONS.some((definition) => definition.id === context.definitionId)
+    ? context.definitionId
+    : null;
+}
+
+function googleDriveFacetSelectionRequiresAcquisition(
+  context: Awaited<ReturnType<typeof requireGoogleDriveIntegrationFacet>>,
+  requested: ReturnType<typeof googleDriveFacetConfig>,
+): boolean {
+  const binding = context.facet.binding;
+  if (
+    !binding ||
+    binding.status !== "active" ||
+    !binding.directlyOwned ||
+    binding.connectionId !== context.connection.id
+  )
+    return true;
+  const previous = GoogleDriveKnowledgeSourceConfig.safeParse(binding.config);
+  if (!previous.success) return true;
+  const selection = (config: ReturnType<typeof googleDriveFacetConfig>) =>
+    config.sources.map((source) => ({
+      ...source,
+      destination: config.destination,
+      syncCadence: config.syncCadence,
+      syncEnabled: true,
+      readPolicy: config.readPolicy,
+    }));
+  return integrationSourceSelectionRequiresAcquisition(
+    selection(previous.data),
+    selection(requested),
   );
 }
 
@@ -1065,14 +1318,34 @@ export async function saveGoogleDriveSource(
   if (existing.accountId !== input.accountId || existing.workspaceId !== input.workspaceId) {
     throw new HTTPException(403, { message: "Google Drive connection authority mismatch" });
   }
-  await requireGoogleDriveSourceConnection(deps, existing, input.subjectId);
+  const existingMetadata = await requireGoogleDriveSourceConnection(
+    deps,
+    existing,
+    input.subjectId,
+  );
   const documentDestination = googleDriveDocumentDestination(input, payload);
-  const verifiedSources = await verifyGoogleDriveSources(deps, {
-    workspaceId: input.workspaceId,
-    subjectId: input.subjectId,
-    connectionId: input.connectionId,
-    sources: payload.sources,
-  });
+  const requestedSelection = payload.sources.map((source) => ({
+    ...source,
+    destination: documentDestination,
+    syncCadence: payload.syncCadence,
+    syncEnabled: payload.syncEnabled,
+    readPolicy: payload.readPolicy,
+  }));
+  const acquiring = integrationSourceSelectionRequiresAcquisition(
+    existingMetadata.selectedSources ??
+      (existingMetadata.selectedSource ? [existingMetadata.selectedSource] : []),
+    requestedSelection,
+  );
+  if (acquiring)
+    await withOrganizationIntegrationAcquisition(deps.db, input, ["google-drive"], async () => {});
+  const verifiedSources = acquiring
+    ? await verifyGoogleDriveSources(deps, {
+        workspaceId: input.workspaceId,
+        subjectId: input.subjectId,
+        connectionId: input.connectionId,
+        sources: payload.sources,
+      })
+    : payload.sources;
   const latest =
     (await getConnectionMetadata(
       deps.db,
@@ -1084,33 +1357,46 @@ export async function saveGoogleDriveSource(
   const previousSources =
     latestMetadata.selectedSources ??
     (latestMetadata.selectedSource ? [latestMetadata.selectedSource] : []);
-  const updated = await transitionConnectionState(deps.db, {
-    workspaceId: input.workspaceId,
-    connectionId: latest.id,
-    visibleToSubjectId: input.subjectId,
-    expectedVersion: latest.version,
-    metadata: GoogleDriveConnectionMetadata.parse({
-      ...latestMetadata,
-      documentDestination,
-      selectedSource: null,
-      selectedSources: verifiedSources.map((verified) => {
-        const previous = previousSources.find((source) => source.id === verified.id);
-        return {
-          id: verified.id,
-          name: verified.name,
-          mimeType: verified.mimeType,
-          driveId: verified.driveId,
-          destination: documentDestination,
-          syncCadence: payload.syncCadence,
-          syncEnabled: payload.syncEnabled,
-          configGeneration: (previous?.configGeneration ?? 0) + 1,
-          readPolicy: payload.readPolicy,
-          selectedAt: new Date().toISOString(),
-        };
-      }),
-    }),
-    updatedBySubjectId: input.subjectId,
-  });
+  const updated = await withOrganizationIntegrationPolicyFence(
+    deps.db,
+    input,
+    async (tx, policy) => {
+      if (integrationSourceSelectionRequiresAcquisition(previousSources, requestedSelection)) {
+        assertOrganizationIntegrationAllowed(policy, "google-drive");
+        if (!acquiring)
+          throw new HTTPException(409, {
+            message: "Google Drive sources changed; verify the selection again",
+          });
+      }
+      return transitionConnectionState(tx, {
+        workspaceId: input.workspaceId,
+        connectionId: latest.id,
+        visibleToSubjectId: input.subjectId,
+        expectedVersion: latest.version,
+        metadata: GoogleDriveConnectionMetadata.parse({
+          ...latestMetadata,
+          documentDestination,
+          selectedSource: null,
+          selectedSources: verifiedSources.map((verified) => {
+            const previous = previousSources.find((source) => source.id === verified.id);
+            return {
+              id: verified.id,
+              name: verified.name,
+              mimeType: verified.mimeType,
+              driveId: verified.driveId,
+              destination: documentDestination,
+              syncCadence: payload.syncCadence,
+              syncEnabled: payload.syncEnabled,
+              configGeneration: (previous?.configGeneration ?? 0) + 1,
+              readPolicy: payload.readPolicy,
+              selectedAt: new Date().toISOString(),
+            };
+          }),
+        }),
+        updatedBySubjectId: input.subjectId,
+      });
+    },
+  );
   if (!updated) {
     throw new HTTPException(409, { message: "Google Drive connection changed; try again" });
   }
@@ -1542,7 +1828,6 @@ async function materializeGoogleDriveKnowledgeSchedules(
           action: { kind: "agent_turn" },
           runMode: "new_session_per_run",
           targetSessionId: null,
-          connectionAuthorities: [],
           agentConfig: knowledgeSourceAgentConfig(action),
           variableSetId: null,
           environmentId: null,
@@ -2108,6 +2393,16 @@ function readGoogleDriveOAuthState(
   if (capability !== "source_read" && capability !== "publish") {
     throw new HTTPException(400, { message: "invalid Google Drive OAuth capability" });
   }
+  const publishingFolderId = optionalString(payload.publishingFolderId) ?? undefined;
+  if (
+    payload.publishingFolderId !== undefined &&
+    (!publishingFolderId ||
+      publishingFolderId.length > 512 ||
+      capability !== "publish" ||
+      !connectionId)
+  ) {
+    throw new HTTPException(400, { message: "invalid Google Drive publishing state" });
+  }
   if (
     (connectionVersion !== undefined && !Number.isInteger(connectionVersion)) ||
     Boolean(connectionId) !== Boolean(connectionVersion)
@@ -2140,6 +2435,7 @@ function readGoogleDriveOAuthState(
       "state.encryptedPkceVerifier",
     ),
     capability,
+    ...(publishingFolderId ? { publishingFolderId } : {}),
     ...(connectionId ? { connectionId, connectionVersion: connectionVersion! } : {}),
     nonce: requiredString(payload.nonce, "state.nonce"),
     iat,