@opengeni/api-router 0.30.3 → 1.0.0

package/src/integrations/google-drive.ts

@@ -1,8 +1,30 @@
+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 type { Settings } from "@opengeni/config";
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
+import { requireConnectOwnerAuthority } from "./connect-authority";
+import {
+  configuredGoogleDriveSyncLimits,
+  googleDriveOAuthCallbackUrl,
+  type Settings,
+} from "@opengeni/config";
 import type { AccessGrant, ScheduledTask, ScheduledTaskScheduleSpec } from "@opengeni/contracts";
 import {
   bindConnectorDocumentDestination,
+  type ConnectorDocumentDestination,
   type ConnectorDocumentDestinationSelection,
 } from "@opengeni/contracts/connector-destinations";
 import {
@@ -36,12 +58,12 @@ import {
 } from "@opengeni/contracts";
 import {
   GOOGLE_DRIVE_INTEGRATION_DEFINITION,
+  CORE_INTEGRATION_DEFINITIONS,
   integrationDefinitionProviderDomain,
 } from "@opengeni/capabilities";
 import {
   captureScheduledTaskRestoreState,
   createValidatedScheduledTask,
-  hasPermission,
   manualScheduledTaskTriggerWorkflowId,
   requireEnvironmentEncryption,
   syncCreatedScheduledTask,
@@ -51,11 +73,16 @@ import type { ApiRouteDeps } from "@opengeni/core";
 import {
   buildConnectionTokenResolver,
   configureIntegrationFacet,
+  integrationFacetConfigureRequestDigest,
   appendKnowledgeSourceAclVersion,
   deauthorizeKnowledgeSourceRetrieval,
   ConnectionDisconnectGenerationError,
   ConnectionDisconnectIdempotencyError,
   consumeIntegrationOAuthStateNonce,
+  finishConnectOperation,
+  getConnectAttempt,
+  type Database,
+  listInstalledApiIntegrations,
   createConnection,
   decryptEnvironmentValue,
   disconnectConnectionIdempotently,
@@ -64,15 +91,16 @@ import {
   getConnectionMetadata,
   getKnowledgeSourceByExternalIdentityForSyncAuthority,
   getKnowledgeSourceForSyncAuthority,
-  getWorkspaceGrant,
   listKnowledgeSourceSyncTasksForConnection,
   loadConnectionCredentialForBroker,
   listIntegrationInstanceFacets,
+  replayCompletedIntegrationFacetOperation,
   transitionConnectionState,
   updateConnection,
   updateScheduledTask,
   upsertKnowledgeProvider,
   upsertKnowledgeSource,
+  withWorkspaceSubjectRls,
   recordKnowledgeLifecycleEvent,
   type PermanentConnectionRefreshFailure,
 } from "@opengeni/db";
@@ -80,8 +108,15 @@ import { googleDriveKnowledgeSourceIdentity } from "@opengeni/documents/google-d
 import { createSignedState, readSignedState } from "@opengeni/github";
 import { readResponseJsonBounded, type FetchLike } from "@opengeni/network";
 import { HTTPException } from "hono/http-exception";
+import {
+  personalOnlyConnectionPrincipalMessage,
+  personalOwnerStateAccepted,
+  personalOwnerVerifiedInState,
+  PERSONAL_OWNER_VERIFIED_STATE_CLAIM,
+} from "../connection-ownership";
 import {
   integrationBaseUrl,
+  oauthStateFailureReturn,
   oauthStateTtlMs,
   requireIntegrationsStateSecret,
 } from "./oauth-client";
@@ -94,6 +129,17 @@ const GOOGLE_RESPONSE_MAX_BYTES = 2 * 1024 * 1024;
 const GOOGLE_REQUEST_TIMEOUT_MS = 10_000;
 const GOOGLE_DRIVE_PAGE_SIZE = 100;
 const GOOGLE_DRIVE_RETURN_PATH = (workspaceId: string) => `/workspaces/${workspaceId}/capabilities`;
+/**
+ * Flow discriminator for this connector's signed OAuth state.
+ *
+ * This state carries no `ownership` field and no provider identity - it is
+ * personal-only by construction - so the `personalOwnerVerified` claim would
+ * otherwise be its sole ownership gate. Its return path is also byte-identical
+ * to the MCP OAuth start's, which signs that path from caller input, so a
+ * caller's own MCP state could be presented here. Requiring an exact flow kind
+ * binds a state to the flow that minted it.
+ */
+const GOOGLE_DRIVE_OAUTH_STATE_KIND = "google_drive_oauth";
 const GOOGLE_DRIVE_RECONSENT_ERROR_CODES = new Set([
   "appNotAuthorizedToFile",
   "authError",
@@ -102,9 +148,13 @@ const GOOGLE_DRIVE_RECONSENT_ERROR_CODES = new Set([
 ]);
 
 type GoogleDriveOAuthState = {
+  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;
   encryptedPkceVerifier: string;
   capability: "source_read" | "publish";
@@ -155,7 +205,7 @@ export async function wakeGoogleDriveSourcesFromWorkspaceEvent(
   );
   let triggered = 0;
   for (const task of tasks) {
-    if (task.action.kind !== "knowledge_source_sync" || task.status !== "active") continue;
+    if (!scheduledTaskKnowledgeSource(task) || task.status !== "active") continue;
     const externalSourceId =
       typeof task.metadata.externalSourceId === "string" ? task.metadata.externalSourceId : null;
     const selectedSource = externalSourceId ? selectedById.get(externalSourceId) : null;
@@ -212,8 +262,11 @@ export async function startGoogleDriveOAuth(
     subjectId: string;
     requestUrl: string;
     payload: GoogleDriveOAuthStartRequest;
+    connectAttemptId?: string;
+    externalContinuation?: ExternalActorContinuation;
   },
 ): Promise<GoogleDriveOAuthStartResponse> {
+  await withOrganizationIntegrationAcquisition(deps.db, input, ["google-drive"], async () => {});
   const google = requireGoogleDriveSettings(deps.settings);
   const existing = input.payload.connectionId
     ? await getConnectionMetadata(
@@ -237,12 +290,24 @@ export async function startGoogleDriveOAuth(
 
   const key = requireEnvironmentEncryption(deps.settings);
   const verifier = randomBytes(48).toString("base64url");
-  const baseUrl = integrationBaseUrl(deps.settings.publicBaseUrl, input.requestUrl);
-  const redirectUri = `${baseUrl}/v1/integrations/google-drive/callback`;
+  const redirectUri = requireGoogleDriveOAuthCallbackUrl(deps.settings);
   const state = createSignedState(requireIntegrationsStateSecret(deps.settings), {
     accountId: input.accountId,
     workspaceId: input.workspaceId,
     subjectId: input.subjectId,
+    kind: GOOGLE_DRIVE_OAUTH_STATE_KIND,
+    ...(input.connectAttemptId ? { connectAttemptId: input.connectAttemptId } : {}),
+    ...(input.externalContinuation
+      ? {
+          encryptedExternalContinuation: encryptEnvironmentValue(
+            key,
+            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: GOOGLE_DRIVE_RETURN_PATH(input.workspaceId),
     encryptedPkceVerifier: encryptEnvironmentValue(key, verifier),
     capability: input.payload.capability,
@@ -289,12 +354,43 @@ export async function completeGoogleDriveOAuthCallback(
     pickedFileIds?: string | undefined;
     requestUrl: string;
   },
-): Promise<{ redirectTo: string }> {
+): Promise<{ redirectTo: string; exactReturn?: boolean }> {
+  const redirectUri = requireGoogleDriveOAuthCallbackUrl(deps.settings);
   const baseUrl = integrationBaseUrl(deps.settings.publicBaseUrl, input.requestUrl);
   const returnBaseUrl = deps.settings.webBaseUrl?.replace(/\/+$/, "") ?? baseUrl;
   let state: GoogleDriveOAuthState | null = null;
+  let exactReturnUrl: string | undefined;
+  let operation: { attemptId: string; operationId: string; inputDigest: string } | undefined;
   try {
     state = readGoogleDriveOAuthState(input.state, deps.settings);
+    if (state.connectAttemptId) {
+      const stored = await getConnectAttempt(deps.db, state, state.connectAttemptId);
+      if (
+        stored.attempt.providerId !==
+          (state.capability === "publish" ? "google-drive-publish" : "google-drive-knowledge") ||
+        stored.attempt.ownership !== "personal"
+      )
+        throw new GoogleDriveCallbackError("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),
+        },
+        "google-drive",
+        Boolean(input.code && !input.error),
+      );
+      if (claim.status === "replayed") return { redirectTo: exactReturnUrl, exactReturn: true };
+    }
     await requireGoogleDriveCallbackGrant(deps, state);
     const consumed = await consumeIntegrationOAuthStateNonce(deps.db, {
       accountId: state.accountId,
@@ -305,7 +401,26 @@ 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)) {
+      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 GoogleDriveCallbackError("provider_denied");
@@ -313,11 +428,11 @@ 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);
     const verifier = decryptEnvironmentValue(key, state.encryptedPkceVerifier);
-    const redirectUri = `${baseUrl}/v1/integrations/google-drive/callback`;
     const fetchImpl = deps.googleDriveFetch ?? fetch;
     const token = await exchangeGoogleAuthorizationCode(
       {
@@ -372,16 +487,6 @@ export async function completeGoogleDriveOAuthCallback(
         : previousMetadata?.outputDestination;
     if (state.capability === "publish") {
       if (!existing) throw new GoogleDriveCallbackError("connection_conflict");
-      await ensureConnectorActionPolicyDefault(deps.db, {
-        accountId: state.accountId,
-        workspaceId: state.workspaceId,
-        subjectId: state.subjectId,
-        connectionId: existing.id,
-        serverId: GOOGLE_DRIVE_PUBLICATION_SERVER_ID,
-        toolName: GOOGLE_DRIVE_PUBLICATION_TOOL_NAME,
-        actionName: GOOGLE_DRIVE_PUBLICATION_CREATE_ACTION,
-        policy: "ask",
-      });
     }
     let refreshToken = token.refreshToken;
     if (!refreshToken && existing) {
@@ -431,34 +536,92 @@ export async function completeGoogleDriveOAuthCallback(
           ? { selectedSources: [previousMetadata.selectedSource] }
           : {}),
     });
-    const connection = existing
-      ? await updateConnection(deps.db, {
-          workspaceId: state.workspaceId,
-          connectionId: existing.id,
-          visibleToSubjectId: state.subjectId,
-          expectedVersion: existing.version,
-          subjectId: state.subjectId,
-          providerDomain: GOOGLE_DRIVE_PROVIDER_DOMAIN,
-          kind: "oauth2",
-          status: "active",
-          credentialEncrypted,
-          grantedScopes,
-          expiresAt: token.expiresAt,
-          metadata,
-          updatedBySubjectId: state.subjectId,
-        })
-      : await createConnection(deps.db, {
+    const acceptedState = state;
+    const persist = async (tx: Database) => {
+      // Capture the validated immutable callback state for delayed persistence.
+      // eslint-disable-next-line no-shadow
+      const state = acceptedState;
+      if (state.capability === "publish" && existing)
+        await ensureConnectorActionPolicyDefault(tx, {
           accountId: state.accountId,
           workspaceId: state.workspaceId,
           subjectId: state.subjectId,
-          providerDomain: GOOGLE_DRIVE_PROVIDER_DOMAIN,
-          kind: "oauth2",
-          credentialEncrypted,
-          grantedScopes,
-          expiresAt: token.expiresAt,
-          metadata,
-          createdBySubjectId: state.subjectId,
+          connectionId: existing.id,
+          serverId: GOOGLE_DRIVE_PUBLICATION_SERVER_ID,
+          toolName: GOOGLE_DRIVE_PUBLICATION_TOOL_NAME,
+          actionName: GOOGLE_DRIVE_PUBLICATION_CREATE_ACTION,
+          policy: "ask",
         });
+      return existing
+        ? updateConnection(tx, {
+            workspaceId: state.workspaceId,
+            connectionId: existing.id,
+            visibleToSubjectId: state.subjectId,
+            expectedVersion: existing.version,
+            subjectId: state.subjectId,
+            providerDomain: GOOGLE_DRIVE_PROVIDER_DOMAIN,
+            kind: "oauth2",
+            status: "active",
+            credentialEncrypted,
+            grantedScopes,
+            expiresAt: token.expiresAt,
+            metadata,
+            updatedBySubjectId: state.subjectId,
+          })
+        : createConnection(tx, {
+            accountId: state.accountId,
+            workspaceId: state.workspaceId,
+            subjectId: state.subjectId,
+            providerDomain: GOOGLE_DRIVE_PROVIDER_DOMAIN,
+            kind: "oauth2",
+            credentialEncrypted,
+            grantedScopes,
+            expiresAt: token.expiresAt,
+            metadata,
+            createdBySubjectId: state.subjectId,
+          });
+    };
+    if (operation) {
+      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 withOrganizationIntegrationAcquisition(
+      deps.db,
+      acceptedState,
+      ["google-drive"],
+      async (tx) => {
+        await requireGoogleDriveCallbackGrant({ ...deps, db: tx }, acceptedState);
+        return persist(tx);
+      },
+    );
     if (!connection) {
       throw new GoogleDriveCallbackError("connection_conflict");
     }
@@ -466,12 +629,16 @@ export async function completeGoogleDriveOAuthCallback(
       redirectTo: googleDriveReturnUrl(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: googleDriveReturnUrl(
         returnBaseUrl,
-        state?.returnPath ?? "/integrations",
+        state?.returnPath ?? failure!.returnPath,
         "error",
-        googleDriveErrorReason(error),
+        failure?.reason ?? googleDriveErrorReason(error),
       ),
     };
   }
@@ -548,19 +715,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,
@@ -679,20 +872,20 @@ async function deauthorizeGoogleDriveConnectionSources(
     connection.workspaceId,
     connection.id,
     async (task) => {
-      if (task.action.initiatingSubjectId !== subjectId) return;
+      if (requireScheduledTaskKnowledgeSource(task).initiatingSubjectId !== subjectId) return;
       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") return;
       await deauthorizeKnowledgeSourceRetrieval(deps.db, {
         accountId: task.accountId,
         workspaceId: task.workspaceId,
-        sourceId: task.action.sourceId,
-        audience: task.action.destination,
-        operationId: `google-drive-deauthorize:${connection.id}:${authorityVersion}:${task.action.sourceId}:${reasonCode}`,
+        sourceId: requireScheduledTaskKnowledgeSource(task).sourceId,
+        audience: requireScheduledTaskKnowledgeSource(task).destination,
+        operationId: `google-drive-deauthorize:${connection.id}:${authorityVersion}:${requireScheduledTaskKnowledgeSource(task).sourceId}:${reasonCode}`,
         reasonCode,
         actor: {
           kind: "human",
@@ -708,7 +901,7 @@ async function forEachGoogleDriveConnectionTask(
   deps: ApiRouteDeps,
   workspaceId: string,
   connectionId: string,
-  fn: (task: ScheduledTask & { action: { kind: "knowledge_source_sync" } }) => Promise<void>,
+  fn: (task: ScheduledTask) => Promise<void>,
 ): Promise<void> {
   const tasks = await listKnowledgeSourceSyncTasksForConnection(deps.db, workspaceId, connectionId);
   for (const task of tasks) {
@@ -829,63 +1022,160 @@ export async function saveGoogleDriveFacetSource(
     throw new HTTPException(400, { message: "invalid Google Drive source selection" });
   }
   const payload = parsedPayload.data;
-  const context = await requireGoogleDriveIntegrationFacet(deps, input);
-  const documentDestination = googleDriveDocumentDestination(input, payload);
-  const verifiedSources = await verifyGoogleDriveSources(deps, {
-    workspaceId: input.workspaceId,
-    subjectId: input.subjectId,
-    connectionId: context.connection.id,
-    sources: payload.sources,
-  });
-  const config = GoogleDriveKnowledgeSourceConfig.parse({
-    sources: verifiedSources.map((verified) => ({
-      id: verified.id,
-      name: verified.name,
-      mimeType: verified.mimeType,
-      ...(verified.driveId ? { driveId: verified.driveId } : {}),
-      sourceKind:
-        verified.id === "root"
-          ? "my_drive"
-          : verified.driveId === verified.id
-            ? "shared_drive"
-            : "folder",
-      includeDescendants: true,
-    })),
-    destination: {
-      authorityKind: documentDestination.authorityKind,
-      authorityAccountId: documentDestination.authorityAccountId,
-      ...(documentDestination.authorityWorkspaceId
-        ? { authorityWorkspaceId: documentDestination.authorityWorkspaceId }
-        : {}),
-      ...(documentDestination.authoritySubjectId
-        ? { authoritySubjectId: documentDestination.authoritySubjectId }
-        : {}),
-      ...(documentDestination.collectionId
-        ? { collectionId: documentDestination.collectionId }
-        : {}),
+  const requestedSources = payload.sources.map((source) => ({
+    ...source,
+    id: validDriveId(source.id, "source.id"),
+  }));
+  if (new Set(requestedSources.map((source) => source.id)).size !== requestedSources.length) {
+    throw new HTTPException(400, { message: "Google Drive sources must be unique" });
+  }
+  const requestedDestination = bindGoogleDriveDocumentDestination(input, payload);
+  const requestedConfig = googleDriveFacetConfig(requestedSources, requestedDestination, payload);
+  const admitted = await withOrganizationIntegrationPolicyFence(
+    deps.db,
+    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,
+          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 };
     },
-    syncCadence: payload.syncCadence,
-    readPolicy: payload.readPolicy,
-  });
-  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,
-      ...(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),
   );
 }
 
+function integrationFacetReceiptDisplayName(result: Record<string, unknown>): string | null {
+  const binding = result.binding;
+  if (!binding || typeof binding !== "object" || Array.isArray(binding)) return null;
+  const bindingRecord = binding as Record<string, unknown>;
+  return typeof bindingRecord.displayName === "string" ? bindingRecord.displayName : null;
+}
+
 export async function saveGoogleDriveSource(
   deps: ApiRouteDeps,
   input: {
@@ -917,14 +1207,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,
@@ -936,33 +1246,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" });
   }
@@ -1108,6 +1431,24 @@ function googleDriveDocumentDestination(
   if (destinationSelection.authorityKind === "personal" && !input.canManagePersonalDestination) {
     throw new HTTPException(403, { message: "personal destination requires the exact actor" });
   }
+  return bindGoogleDriveDocumentDestination(input, payload);
+}
+
+function bindGoogleDriveDocumentDestination(
+  input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+  },
+  payload: {
+    destination?: ConnectorDocumentDestinationSelection | undefined;
+    targetScope?: "user" | "workspace" | "organization" | undefined;
+  },
+): ConnectorDocumentDestination {
+  const destinationSelection: ConnectorDocumentDestinationSelection = payload.destination ?? {
+    authorityKind: "workspace",
+    collectionId: null,
+  };
   return bindConnectorDocumentDestination(destinationSelection, {
     accountId: input.accountId,
     workspaceId: input.workspaceId,
@@ -1115,6 +1456,51 @@ function googleDriveDocumentDestination(
   });
 }
 
+function googleDriveFacetConfig(
+  sources: ReadonlyArray<{
+    id: string;
+    name: string;
+    mimeType: string;
+    driveId: string | null;
+  }>,
+  documentDestination: ConnectorDocumentDestination,
+  payload: {
+    syncCadence: "manual" | "hourly" | "daily";
+    readPolicy: "allow" | "ask" | "block";
+  },
+) {
+  return GoogleDriveKnowledgeSourceConfig.parse({
+    sources: sources.map((source) => ({
+      id: source.id,
+      name: source.name,
+      mimeType: source.mimeType,
+      ...(source.driveId ? { driveId: source.driveId } : {}),
+      sourceKind:
+        source.id === "root"
+          ? "my_drive"
+          : source.driveId === source.id
+            ? "shared_drive"
+            : "folder",
+      includeDescendants: true,
+    })),
+    destination: {
+      authorityKind: documentDestination.authorityKind,
+      authorityAccountId: documentDestination.authorityAccountId,
+      ...(documentDestination.authorityWorkspaceId
+        ? { authorityWorkspaceId: documentDestination.authorityWorkspaceId }
+        : {}),
+      ...(documentDestination.authoritySubjectId
+        ? { authoritySubjectId: documentDestination.authoritySubjectId }
+        : {}),
+      ...(documentDestination.collectionId
+        ? { collectionId: documentDestination.collectionId }
+        : {}),
+    },
+    syncCadence: payload.syncCadence,
+    readPolicy: payload.readPolicy,
+  });
+}
+
 async function verifyGoogleDriveSources(
   deps: ApiRouteDeps,
   input: {
@@ -1187,11 +1573,11 @@ async function materializeGoogleDriveKnowledgeSchedules(
     let source = null as Awaited<ReturnType<typeof upsertKnowledgeSource>> | null;
     let existingTask = null as (typeof connectionTasks)[number] | null;
     for (const task of connectionTasks) {
-      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;
@@ -1282,13 +1668,8 @@ async function materializeGoogleDriveKnowledgeSchedules(
         kind: input.connection.kind,
       },
       limits: {
-        maxItems: 500,
-        maxBytes: 500_000_000,
-        maxFileBytes: 100_000_000,
-        maxProviderRequests: 1_000,
-        maxElapsedSeconds: 300,
+        ...configuredGoogleDriveSyncLimits(deps.settings),
         maxConcurrency: 4,
-        maxFailureDetails: 25,
       },
     };
     const schedule = googleDriveSchedule(selectedSource.syncCadence);
@@ -1298,7 +1679,10 @@ async function materializeGoogleDriveKnowledgeSchedules(
       task = await updateScheduledTask(deps.db, input.workspaceId, existingTask.id, {
         name: `Sync Google Drive: ${selectedSource.name}`,
         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: "google_drive",
@@ -1330,15 +1714,11 @@ async function materializeGoogleDriveKnowledgeSchedules(
           status: "active",
           schedule,
           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,
@@ -1363,11 +1743,11 @@ async function materializeGoogleDriveKnowledgeSchedules(
   }
 
   for (const task of connectionTasks) {
-    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;
@@ -1406,15 +1786,15 @@ async function materializeGoogleDriveKnowledgeSchedules(
   }
 }
 
-export async function revokeKnowledgeSourceScheduleAuthorization(
+export async function preflightKnowledgeSourceScheduleAuthorization(
   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",
@@ -1430,65 +1810,138 @@ export async function revokeKnowledgeSourceScheduleAuthorization(
   if (!externalSourceId) {
     throw new HTTPException(409, { message: "knowledge source 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: "knowledge source connection is unavailable for durable disable",
+  // A deselected/disconnected source still owns a retained task that must be
+  // deletable. The row-locked task revision below freezes this descriptor;
+  // cleanup mutates only its exact accepted generations.
+}
+
+export async function revokeKnowledgeSourceScheduleAuthorization(
+  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",
     });
   }
-  const metadata = requireGoogleDriveConnection(connection, input.subjectId);
-  const sources =
-    metadata.selectedSources ?? (metadata.selectedSource ? [metadata.selectedSource] : []);
-  const selected = sources.find((source) => source.id === externalSourceId);
-  let revocationVersion = connection.version;
-  if (selected?.syncEnabled) {
-    const updated = await transitionConnectionState(deps.db, {
-      workspaceId: task.workspaceId,
-      connectionId: connection.id,
-      visibleToSubjectId: input.subjectId,
-      expectedVersion: connection.version,
-      metadata: GoogleDriveConnectionMetadata.parse({
-        ...metadata,
-        selectedSource: null,
-        selectedSources: sources.map((source) =>
-          source.id === externalSourceId
-            ? {
-                ...source,
-                syncEnabled: false,
-                configGeneration: source.configGeneration + 1,
-              }
-            : source,
-        ),
-      }),
-      updatedBySubjectId: input.subjectId,
+  if (task.metadata.connectorKind !== "google_drive") {
+    throw new HTTPException(409, {
+      message: "knowledge source schedule connector cannot be durably disabled",
     });
-    if (!updated) {
-      throw new HTTPException(409, {
-        message: "knowledge source connection changed; retry schedule deletion",
-      });
-    }
-    revocationVersion = updated.version;
   }
-  const resolved = await getKnowledgeSourceForSyncAuthority(deps.db, {
+  const externalSourceId =
+    typeof task.metadata.externalSourceId === "string" ? task.metadata.externalSourceId.trim() : "";
+  if (!externalSourceId) {
+    throw new HTTPException(409, { message: "knowledge source schedule identity is incomplete" });
+  }
+  await cleanupKnowledgeSourceScheduleAuthorization(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 cleanupKnowledgeSourceScheduleAuthorization(
+  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 revocationVersion = input.connectionVersion;
+    if (connection) {
+      const metadata = requireGoogleDriveConnection(connection, input.subjectId);
+      const sources =
+        metadata.selectedSources ?? (metadata.selectedSource ? [metadata.selectedSource] : []);
+      revocationVersion = connection.version;
+      const updated = await transitionConnectionState(tx, {
+        workspaceId: input.workspaceId,
+        connectionId: connection.id,
+        visibleToSubjectId: input.subjectId,
+        expectedVersion: connection.version,
+        metadata: GoogleDriveConnectionMetadata.parse({
+          ...metadata,
+          selectedSource: null,
+          selectedSources: sources.map((source) =>
+            source.id === input.externalSourceId
+              ? {
+                  ...source,
+                  syncEnabled: false,
+                  configGeneration: source.configGeneration + 1,
+                }
+              : source,
+          ),
+        }),
+        updatedBySubjectId: input.subjectId,
+      });
+      if (!updated) {
+        throw new HTTPException(409, {
+          message: "knowledge source connection changed; retry schedule deletion",
+        });
+      }
+      revocationVersion = 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: "knowledge source changed; retry schedule deletion",
+      });
+    }
+    await recordKnowledgeLifecycleEvent(tx, {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
       targetKind: "source",
       targetId: resolved.source.id,
       eventType: "deleted",
       expectedGeneration: resolved.source.lifecycleGeneration,
-      operationId: `knowledge-schedule-delete:${task.id}:${revocationVersion}`,
+      operationId: `knowledge-schedule-delete:${input.taskId}:${revocationVersion}`,
       reasonCode: "schedule_deleted",
       actor: {
         kind: "human",
@@ -1496,7 +1949,7 @@ export async function revokeKnowledgeSourceScheduleAuthorization(
         initiatingHumanSubjectId: input.subjectId,
       },
     });
-  }
+  });
 }
 
 function knowledgeSourceScheduleControl(task: ScheduledTask): {
@@ -1614,6 +2067,16 @@ function requireGoogleDriveSettings(settings: Settings): {
   return { clientId, clientSecret };
 }
 
+function requireGoogleDriveOAuthCallbackUrl(settings: Settings): string {
+  const callbackUrl = googleDriveOAuthCallbackUrl(settings.publicBaseUrl);
+  if (!callbackUrl) {
+    throw new HTTPException(503, {
+      message: "Google Drive requires a canonical OPENGENI_PUBLIC_BASE_URL origin",
+    });
+  }
+  return callbackUrl;
+}
+
 function requireGoogleDriveConnection(connection: GoogleDriveConnectionRecord, subjectId: string) {
   const parsed = GoogleDriveConnectionMetadata.safeParse(connection.metadata);
   if (
@@ -1799,6 +2262,13 @@ function readGoogleDriveOAuthState(
   if (iat === undefined || now < iat || now - iat > oauthStateTtlMs / 1000) {
     throw new HTTPException(400, { message: "invalid or expired Google Drive 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,
+  // so this adds no new breakage.
+  if (payload.kind !== GOOGLE_DRIVE_OAUTH_STATE_KIND) {
+    throw new HTTPException(400, { message: "invalid Google Drive OAuth state" });
+  }
   const accountId = requiredString(payload.accountId, "state.accountId");
   const workspaceId = requiredString(payload.workspaceId, "state.workspaceId");
   const subjectId = requiredString(payload.subjectId, "state.subjectId");
@@ -1823,6 +2293,22 @@ function readGoogleDriveOAuthState(
     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,
     encryptedPkceVerifier: requiredString(
       payload.encryptedPkceVerifier,
@@ -1839,16 +2325,22 @@ async function requireGoogleDriveCallbackGrant(
   deps: ApiRouteDeps,
   state: GoogleDriveOAuthState,
 ): 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: "Google Drive OAuth subject no longer has permission for this workspace",
+    throw new HTTPException(422, {
+      message: personalOnlyConnectionPrincipalMessage("Google Drive"),
     });
   }
+  await requireConnectOwnerAuthority(deps.db, state, "connections:write");
 }
 
 async function exchangeGoogleAuthorizationCode(