@opengeni/api-router 0.30.3 → 2.2.0-canary.0

package/src/integrations/google-drive.ts

@@ -1,8 +1,13 @@
 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 {
@@ -51,6 +56,7 @@ import type { ApiRouteDeps } from "@opengeni/core";
 import {
   buildConnectionTokenResolver,
   configureIntegrationFacet,
+  integrationFacetConfigureRequestDigest,
   appendKnowledgeSourceAclVersion,
   deauthorizeKnowledgeSourceRetrieval,
   ConnectionDisconnectGenerationError,
@@ -68,11 +74,13 @@ import {
   listKnowledgeSourceSyncTasksForConnection,
   loadConnectionCredentialForBroker,
   listIntegrationInstanceFacets,
+  replayCompletedIntegrationFacetOperation,
   transitionConnectionState,
   updateConnection,
   updateScheduledTask,
   upsertKnowledgeProvider,
   upsertKnowledgeSource,
+  withWorkspaceSubjectRls,
   recordKnowledgeLifecycleEvent,
   type PermanentConnectionRefreshFailure,
 } from "@opengeni/db";
@@ -80,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,
@@ -94,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",
@@ -105,6 +130,8 @@ 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";
@@ -237,12 +264,15 @@ 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,
+    // 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,
@@ -290,6 +320,7 @@ export async function completeGoogleDriveOAuthCallback(
     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;
@@ -317,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(
       {
@@ -829,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, {
@@ -877,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 }
         : {}),
@@ -886,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: {
@@ -1108,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,
@@ -1115,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: {
@@ -1282,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);
@@ -1333,6 +1435,7 @@ async function materializeGoogleDriveKnowledgeSchedules(
           action,
           runMode: "new_session_per_run",
           targetSessionId: null,
+          connectionAuthorities: [],
           agentConfig: {
             prompt: "Knowledge source synchronization",
             resources: [],
@@ -1406,7 +1509,7 @@ async function materializeGoogleDriveKnowledgeSchedules(
   }
 }
 
-export async function revokeKnowledgeSourceScheduleAuthorization(
+export async function preflightKnowledgeSourceScheduleAuthorization(
   deps: ApiRouteDeps,
   input: { task: ScheduledTask; subjectId: string },
 ): Promise<void> {
@@ -1430,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",
@@ -1496,7 +1672,7 @@ export async function revokeKnowledgeSourceScheduleAuthorization(
         initiatingHumanSubjectId: input.subjectId,
       },
     });
-  }
+  });
 }
 
 function knowledgeSourceScheduleControl(task: ScheduledTask): {
@@ -1614,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 (
@@ -1799,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");
@@ -1823,6 +2016,7 @@ function readGoogleDriveOAuthState(
     accountId,
     workspaceId,
     subjectId,
+    personalOwnerVerified: personalOwnerVerifiedInState(payload),
     returnPath,
     encryptedPkceVerifier: requiredString(
       payload.encryptedPkceVerifier,
@@ -1839,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 ||