@opengeni/api-router 0.30.1 → 2.1.0-canary.0

package/src/integrations/google-drive.ts

@@ -1,13 +1,22 @@
 import { createHash, randomBytes } from "node:crypto";
-import type { Settings } from "@opengeni/config";
+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 {
   GOOGLE_DRIVE_CREDENTIAL_LABEL,
   GOOGLE_DRIVE_CREDENTIAL_ROLE,
+  GOOGLE_DRIVE_FILE_SCOPE,
+  GOOGLE_DRIVE_PUBLICATION_CREATE_ACTION,
+  GOOGLE_DRIVE_PUBLICATION_SERVER_ID,
+  GOOGLE_DRIVE_PUBLICATION_TOOL_NAME,
   GOOGLE_DRIVE_PROVIDER_DOMAIN,
   GOOGLE_DRIVE_READONLY_SCOPE,
   GoogleDriveKnowledgeSourceConfig,
@@ -16,6 +25,7 @@ import {
   GoogleDriveConnectionLifecycle,
   GoogleDriveConnectionMetadata,
   GoogleDriveOAuthStartResponse,
+  GoogleDriveOutputDestination,
   SaveGoogleDriveIntegrationSourceRequest,
   SaveGoogleDriveSourceRequest,
   googleDriveOAuthScopeDecision,
@@ -46,6 +56,7 @@ import type { ApiRouteDeps } from "@opengeni/core";
 import {
   buildConnectionTokenResolver,
   configureIntegrationFacet,
+  integrationFacetConfigureRequestDigest,
   appendKnowledgeSourceAclVersion,
   deauthorizeKnowledgeSourceRetrieval,
   ConnectionDisconnectGenerationError,
@@ -55,6 +66,7 @@ import {
   decryptEnvironmentValue,
   disconnectConnectionIdempotently,
   encryptEnvironmentValue,
+  ensureConnectorActionPolicyDefault,
   getConnectionMetadata,
   getKnowledgeSourceByExternalIdentityForSyncAuthority,
   getKnowledgeSourceForSyncAuthority,
@@ -62,11 +74,13 @@ import {
   listKnowledgeSourceSyncTasksForConnection,
   loadConnectionCredentialForBroker,
   listIntegrationInstanceFacets,
+  replayCompletedIntegrationFacetOperation,
   transitionConnectionState,
   updateConnection,
   updateScheduledTask,
   upsertKnowledgeProvider,
   upsertKnowledgeSource,
+  withWorkspaceSubjectRls,
   recordKnowledgeLifecycleEvent,
   type PermanentConnectionRefreshFailure,
 } from "@opengeni/db";
@@ -74,6 +88,12 @@ 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,
   oauthStateTtlMs,
@@ -88,6 +108,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",
@@ -99,8 +130,11 @@ type GoogleDriveOAuthState = {
   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";
   connectionId?: string;
   connectionVersion?: number;
   nonce: string;
@@ -219,30 +253,51 @@ export async function startGoogleDriveOAuth(
   if (input.payload.connectionId && !existing) {
     throw new HTTPException(404, { message: "Google Drive connection not found" });
   }
+  if (input.payload.capability === "publish" && !existing) {
+    throw new HTTPException(409, {
+      message: "Connect Google Drive for source access before enabling publishing",
+    });
+  }
   if (existing) {
     requireGoogleDriveConnection(existing, input.subjectId);
   }
 
   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,
+    // 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 authorizationUrl = new URL(GOOGLE_AUTHORIZATION_URL);
   authorizationUrl.searchParams.set("client_id", google.clientId);
   authorizationUrl.searchParams.set("redirect_uri", redirectUri);
   authorizationUrl.searchParams.set("response_type", "code");
-  authorizationUrl.searchParams.set("scope", GOOGLE_DRIVE_READONLY_SCOPE);
+  authorizationUrl.searchParams.set(
+    "scope",
+    input.payload.capability === "publish" ? GOOGLE_DRIVE_FILE_SCOPE : GOOGLE_DRIVE_READONLY_SCOPE,
+  );
   authorizationUrl.searchParams.set("access_type", "offline");
   authorizationUrl.searchParams.set("include_granted_scopes", "true");
-  authorizationUrl.searchParams.set("prompt", "consent select_account");
+  authorizationUrl.searchParams.set(
+    "prompt",
+    input.payload.capability === "publish" ? "consent" : "consent select_account",
+  );
+  if (input.payload.capability === "publish") {
+    authorizationUrl.searchParams.set("trigger_onepick", "true");
+    authorizationUrl.searchParams.set("allow_folder_selection", "true");
+    authorizationUrl.searchParams.set("allow_multiple", "false");
+    authorizationUrl.searchParams.set("mimetypes", GOOGLE_DRIVE_FOLDER_MIME_TYPE);
+  }
   authorizationUrl.searchParams.set("state", state);
   authorizationUrl.searchParams.set("code_challenge_method", "S256");
   authorizationUrl.searchParams.set(
@@ -261,9 +316,11 @@ export async function completeGoogleDriveOAuthCallback(
     code?: string | undefined;
     state?: string | undefined;
     error?: string | undefined;
+    pickedFileIds?: string | undefined;
     requestUrl: string;
   },
 ): Promise<{ redirectTo: string }> {
+  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;
@@ -291,7 +348,6 @@ export async function completeGoogleDriveOAuthCallback(
     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(
       {
@@ -303,10 +359,15 @@ export async function completeGoogleDriveOAuthCallback(
       },
       fetchImpl,
     );
-    const scopeDecision = googleDriveOAuthScopeDecision(token.scopes);
+    const grantedScopes = [...new Set(token.scopes)].sort();
+    const scopeDecision = googleDriveOAuthScopeDecision(grantedScopes);
+    const requiredCapability =
+      state.capability === "publish" ? "publish_file" : "recursive_source_sync";
     if (
-      scopeDecision.accessMode !== "readonly" ||
-      !scopeDecision.capabilities.includes("recursive_source_sync")
+      !scopeDecision.accessMode ||
+      !scopeDecision.capabilities.includes(requiredCapability) ||
+      (state.capability === "publish" &&
+        !scopeDecision.capabilities.includes("recursive_source_sync"))
     ) {
       throw new GoogleDriveCallbackError("scope_not_granted");
     }
@@ -331,6 +392,27 @@ export async function completeGoogleDriveOAuthCallback(
     const previousMetadata = existing
       ? GoogleDriveConnectionMetadata.parse(existing.metadata)
       : null;
+    const outputDestination =
+      state.capability === "publish"
+        ? await verifyPickedGoogleDriveOutputDestination(
+            token.accessToken,
+            input.pickedFileIds,
+            fetchImpl,
+          )
+        : 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) {
       const previousCredential = await loadConnectionCredentialForBroker(deps.db, deps.settings, {
@@ -353,7 +435,7 @@ export async function completeGoogleDriveOAuthCallback(
         refresh_token: refreshToken,
         token_type: token.tokenType,
         ...(token.expiresAt ? { expires_at: token.expiresAt.toISOString() } : {}),
-        scope: token.scopes.join(" "),
+        scope: grantedScopes.join(" "),
         token_endpoint: GOOGLE_TOKEN_URL,
         client_id: google.clientId,
         client_secret: google.clientSecret,
@@ -369,6 +451,7 @@ export async function completeGoogleDriveOAuthCallback(
       verifiedAt: new Date().toISOString(),
       accessMode: scopeDecision.accessMode,
       lifecycle: googleDriveLifecycle("active"),
+      ...(outputDestination ? { outputDestination } : {}),
       ...(previousMetadata?.documentDestination
         ? { documentDestination: previousMetadata.documentDestination }
         : {}),
@@ -389,7 +472,7 @@ export async function completeGoogleDriveOAuthCallback(
           kind: "oauth2",
           status: "active",
           credentialEncrypted,
-          grantedScopes: token.scopes,
+          grantedScopes,
           expiresAt: token.expiresAt,
           metadata,
           updatedBySubjectId: state.subjectId,
@@ -401,7 +484,7 @@ export async function completeGoogleDriveOAuthCallback(
           providerDomain: GOOGLE_DRIVE_PROVIDER_DOMAIN,
           kind: "oauth2",
           credentialEncrypted,
-          grantedScopes: token.scopes,
+          grantedScopes,
           expiresAt: token.expiresAt,
           metadata,
           createdBySubjectId: state.subjectId,
@@ -776,43 +859,50 @@ export async function saveGoogleDriveFacetSource(
     throw new HTTPException(400, { message: "invalid Google Drive source selection" });
   }
   const payload = parsedPayload.data;
+  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 replayed = await replayCompletedIntegrationFacetOperation<IntegrationFacetMutationResult>(
+    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({
+          capabilityId: input.capabilityId,
+          instanceKey: input.instanceKey,
+          facetKey: input.facetKey,
+          displayName,
+          config: requestedConfig,
+          ...(payload.expectedVersion !== undefined
+            ? { expectedVersion: payload.expectedVersion }
+            : {}),
+        });
+      },
+    },
+  );
+  if (replayed) return IntegrationFacetMutationResult.parse(replayed);
   const context = await requireGoogleDriveIntegrationFacet(deps, input);
-  const documentDestination = googleDriveDocumentDestination(input, payload);
-  const verifiedSources = await verifyGoogleDriveSources(deps, {
+  googleDriveDocumentDestination(input, payload);
+  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 }
-        : {}),
-    },
-    syncCadence: payload.syncCadence,
-    readPolicy: payload.readPolicy,
+    sources: requestedSources,
   });
   return IntegrationFacetMutationResult.parse(
     await configureIntegrationFacet(deps.db, {
@@ -824,7 +914,7 @@ export async function saveGoogleDriveFacetSource(
       facetKey: input.facetKey,
       displayName:
         context.facet.binding?.displayName ?? `${input.instanceKey} — Google Drive content`,
-      config,
+      config: requestedConfig,
       ...(payload.expectedVersion !== undefined
         ? { expectedVersion: payload.expectedVersion }
         : {}),
@@ -833,6 +923,13 @@ export async function saveGoogleDriveFacetSource(
   );
 }
 
+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: {
@@ -935,6 +1032,53 @@ export async function saveGoogleDriveSource(
   return updated;
 }
 
+async function verifyPickedGoogleDriveOutputDestination(
+  accessToken: string,
+  rawPickedFileIds: string | undefined,
+  fetchImpl: FetchLike,
+) {
+  const pickedFileIds = uniqueStrings((rawPickedFileIds ?? "").split(","));
+  if (pickedFileIds.length !== 1) {
+    throw new GoogleDriveCallbackError("output_folder_required");
+  }
+  const folderId = validDriveId(pickedFileIds[0]!, "picked_file_ids");
+  const url = new URL(`${GOOGLE_DRIVE_API_BASE}/files/${encodeURIComponent(folderId)}`);
+  url.searchParams.set("supportsAllDrives", "true");
+  url.searchParams.set("fields", "id,name,mimeType,driveId,trashed,capabilities(canAddChildren)");
+  const response = await providerFetch(fetchImpl, url, {
+    headers: { authorization: `Bearer ${accessToken}`, accept: "application/json" },
+  });
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => undefined);
+    throw new GoogleDriveCallbackError("output_folder_unavailable");
+  }
+  const record = objectRecord(
+    await readResponseJsonBounded<unknown>(
+      response,
+      GOOGLE_RESPONSE_MAX_BYTES,
+      "Google Drive picked output folder",
+    ),
+  );
+  const driveId = optionalString(record.driveId);
+  const capabilities = objectRecord(record.capabilities);
+  if (
+    requiredString(record.id, "Google Drive folder id") !== folderId ||
+    requiredString(record.mimeType, "Google Drive folder MIME type") !==
+      GOOGLE_DRIVE_FOLDER_MIME_TYPE ||
+    record.trashed === true ||
+    capabilities.canAddChildren !== true
+  ) {
+    throw new GoogleDriveCallbackError("output_folder_unavailable");
+  }
+  return GoogleDriveOutputDestination.parse({
+    folderId,
+    folderName: requiredString(record.name, "Google Drive folder name"),
+    driveId: driveId ?? null,
+    location: driveId ? "shared_drive" : "my_drive",
+    selectedAt: new Date().toISOString(),
+  });
+}
+
 async function requireGoogleDriveIntegrationFacet(
   deps: ApiRouteDeps,
   input: {
@@ -1008,6 +1152,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,
@@ -1015,6 +1177,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: {
@@ -1182,13 +1389,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);
@@ -1233,6 +1435,7 @@ async function materializeGoogleDriveKnowledgeSchedules(
           action,
           runMode: "new_session_per_run",
           targetSessionId: null,
+          connectionAuthorities: [],
           agentConfig: {
             prompt: "Knowledge source synchronization",
             resources: [],
@@ -1306,7 +1509,7 @@ async function materializeGoogleDriveKnowledgeSchedules(
   }
 }
 
-export async function revokeKnowledgeSourceScheduleAuthorization(
+export async function preflightKnowledgeSourceScheduleAuthorization(
   deps: ApiRouteDeps,
   input: { task: ScheduledTask; subjectId: string },
 ): Promise<void> {
@@ -1330,65 +1533,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 (task.action.kind !== "knowledge_source_sync") return;
+  if (
+    task.action.initiatingSubjectId !== input.subjectId ||
+    task.action.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,
+    connectionId: task.action.connection.connectionId,
+    connectionVersion: task.action.connection.connectionVersion,
     sourceId: task.action.sourceId,
+    sourceLifecycleGeneration: task.action.sourceLifecycleGeneration,
+    sourceConfigGeneration: task.action.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",
@@ -1396,7 +1672,7 @@ export async function revokeKnowledgeSourceScheduleAuthorization(
         initiatingHumanSubjectId: input.subjectId,
       },
     });
-  }
+  });
 }
 
 function knowledgeSourceScheduleControl(task: ScheduledTask): {
@@ -1514,6 +1790,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 (
@@ -1699,6 +1985,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");
@@ -1708,6 +2001,11 @@ function readGoogleDriveOAuthState(
   }
   const connectionId = optionalString(payload.connectionId) ?? undefined;
   const connectionVersion = numberValue(payload.connectionVersion);
+  const capabilityValue = optionalString(payload.capability);
+  const capability = capabilityValue ?? "source_read";
+  if (capability !== "source_read" && capability !== "publish") {
+    throw new HTTPException(400, { message: "invalid Google Drive OAuth capability" });
+  }
   if (
     (connectionVersion !== undefined && !Number.isInteger(connectionVersion)) ||
     Boolean(connectionId) !== Boolean(connectionVersion)
@@ -1718,11 +2016,13 @@ function readGoogleDriveOAuthState(
     accountId,
     workspaceId,
     subjectId,
+    personalOwnerVerified: personalOwnerVerifiedInState(payload),
     returnPath,
     encryptedPkceVerifier: requiredString(
       payload.encryptedPkceVerifier,
       "state.encryptedPkceVerifier",
     ),
+    capability,
     ...(connectionId ? { connectionId, connectionVersion: connectionVersion! } : {}),
     nonce: requiredString(payload.nonce, "state.nonce"),
     iat,
@@ -1733,6 +2033,21 @@ async function requireGoogleDriveCallbackGrant(
   deps: ApiRouteDeps,
   state: GoogleDriveOAuthState,
 ): Promise<void> {
+  // 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 (
+    !personalOwnerStateAccepted({
+      ownership: "personal",
+      subjectId: state.subjectId,
+      personalOwnerVerified: state.personalOwnerVerified,
+    })
+  ) {
+    throw new HTTPException(422, {
+      message: personalOnlyConnectionPrincipalMessage("Google Drive"),
+    });
+  }
   const grant = await getWorkspaceGrant(deps.db, state.subjectId, state.workspaceId);
   if (
     !grant ||
@@ -1975,7 +2290,7 @@ async function googleDriveApiRequest(
     if (!resolved || resolved.version !== connectionVersion) {
       throw new HTTPException(409, { message: "Google Drive connection changed; try again" });
     }
-    await requireGoogleDriveSourceConnection(deps, resolved, input.subjectId);
+    await requireGoogleDriveApiConnection(deps, resolved, input.subjectId);
   };
   let credential = await resolve(false);
   if (credential.status !== "ok") {