@opengeni/api-router 0.30.1 → 1.0.0

package/src/integrations/provider-oauth.ts

@@ -1,3 +1,5 @@
+import { withOrganizationIntegrationAcquisition } from "@opengeni/db/organization-integration-policy";
+import { claimOAuthAcquisition, finishOAuthAcquisition } from "./oauth-client";
 import { Buffer } from "node:buffer";
 import { createHash, randomBytes } from "node:crypto";
 
@@ -18,15 +20,21 @@ import {
   type ApiIntegrationOAuthStartRequest,
   type ConnectionOwnership,
 } from "@opengeni/contracts";
-import { hasPermission, requireEnvironmentEncryption, type ApiRouteDeps } from "@opengeni/core";
+import {
+  integrationKeyForConnectProvider,
+  requireEnvironmentEncryption,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
 import {
   consumeIntegrationOAuthStateNonce,
   decryptEnvironmentValue,
   encryptEnvironmentValue,
   getConnectionMetadata,
-  getWorkspaceGrant,
   loadConnectionCredentialForBroker,
   persistProviderOAuthConnection,
+  getConnectAttempt,
+  finishConnectOperation,
 } from "@opengeni/db";
 import { createSignedState, readSignedState } from "@opengeni/github";
 import {
@@ -36,11 +44,20 @@ import {
   type FetchLike,
 } from "@opengeni/network";
 import { HTTPException } from "hono/http-exception";
+import { requireConnectOwnerAuthority } from "./connect-authority";
 
+import {
+  assertConnectionOwnershipAllowedForPrincipal,
+  personalOwnerStateAccepted,
+  personalOwnerVerifiedInState,
+  PERSONAL_OWNER_VERIFIED_STATE_CLAIM,
+} from "../connection-ownership";
 import {
   integrationBaseUrl,
+  oauthStateFailureReturn,
   oauthStateTtlMs,
   requireIntegrationsStateSecret,
+  workspaceIntegrationsPath,
 } from "./oauth-client";
 
 const PROVIDER_OAUTH_CALLBACK_PATH = "/v1/integrations/provider-oauth/callback";
@@ -56,10 +73,13 @@ type ProviderOAuthClient = {
 };
 
 type ProviderOAuthState = {
+  connectAttemptId?: string;
+  externalContinuation?: ExternalActorContinuation;
   accountId: string;
   workspaceId: string;
   subjectId: string;
   ownership: ConnectionOwnership;
+  personalOwnerVerified: boolean;
   definitionId: string;
   definitionFingerprint: string;
   providerDomain: string;
@@ -91,6 +111,7 @@ type ProviderIdentity = {
 
 type ProviderOAuthFailureReason =
   | "state_invalid"
+  | "state_expired"
   | "state_replayed"
   | "provider_denied"
   | "missing_code"
@@ -117,11 +138,20 @@ export async function startApiIntegrationProviderOAuth(
     accountId: string;
     workspaceId: string;
     subjectId: string;
+    /**
+     * False for every principal that cannot own a personal Connection (API
+     * keys, the configured key, services, agent attempts). Resolved by the
+     * route from the live authenticated principal, never inferred here.
+     */
+    personalOwnershipAllowed: boolean;
+    externalContinuation?: ExternalActorContinuation;
+    connectAttemptId?: string;
     requestUrl: string;
     payload: ApiIntegrationOAuthStartRequest;
   },
 ): Promise<OAuthStartResponse> {
   const definition = requiredDefinition(input.payload.definitionId);
+  await withOrganizationIntegrationAcquisition(deps.db, input, [definition.id], async () => {});
   const providerDomain = integrationDefinitionProviderDomain(definition);
   const existing = input.payload.connectionId
     ? await getConnectionMetadata(
@@ -155,7 +185,16 @@ export async function startApiIntegrationProviderOAuth(
       message: "The selected Connection ownership does not match this OAuth request",
     });
   }
-  const ownership = existingOwnership ?? input.payload.ownership ?? "personal";
+  // API callers choose ownership explicitly; reconnects preserve the saved choice.
+  const ownership = existingOwnership ?? input.payload.ownership ?? null;
+  if (ownership === null) {
+    throw new HTTPException(422, {
+      message:
+        'ownership is required: choose "workspace" to share this Connection with the workspace, ' +
+        'or "personal" to connect only for yourself',
+    });
+  }
+  assertConnectionOwnershipAllowedForPrincipal(ownership, input.personalOwnershipAllowed);
   const authorizeScopes = uniqueStrings([
     ...(existing?.grantedScopes ?? []),
     ...definition.authentication.scopes,
@@ -164,15 +203,18 @@ export async function startApiIntegrationProviderOAuth(
   const verifier = randomBytes(48).toString("base64url");
   const key = requireEnvironmentEncryption(deps.settings);
   const baseUrl = integrationBaseUrl(deps.settings.publicBaseUrl, input.requestUrl);
-  const redirectUri = `${baseUrl}${PROVIDER_OAUTH_CALLBACK_PATH}`;
+  const redirectUri = `${baseUrl}${providerOAuthCallbackPath(definition)}`;
   const returnPath = safeReturnPath(
-    input.payload.returnPath ?? `/workspaces/${input.workspaceId}/capabilities`,
+    input.payload.returnPath ?? workspaceIntegrationsPath(input.workspaceId),
   );
   const state = createSignedState(requireIntegrationsStateSecret(deps.settings), {
     accountId: input.accountId,
     workspaceId: input.workspaceId,
     subjectId: input.subjectId,
     ownership,
+    // Signed record that a live principal was checked; the callback has no
+    // principal of its own and enforces exactly this decision.
+    [PERSONAL_OWNER_VERIFIED_STATE_CLAIM]: input.personalOwnershipAllowed,
     definitionId: definition.id,
     definitionFingerprint: providerDefinitionFingerprint(definition),
     providerDomain,
@@ -181,6 +223,15 @@ export async function startApiIntegrationProviderOAuth(
     clientId: client.clientId,
     tokenEndpointAuthMethod: client.tokenEndpointAuthMethod,
     returnPath,
+    ...(input.connectAttemptId ? { connectAttemptId: input.connectAttemptId } : {}),
+    ...(input.externalContinuation
+      ? {
+          encryptedExternalContinuation: encryptEnvironmentValue(
+            key,
+            JSON.stringify(ExternalActorContinuation.parse(input.externalContinuation)),
+          ),
+        }
+      : {}),
     ...(existing
       ? {
           connectionId: existing.id,
@@ -221,12 +272,42 @@ export async function completeApiIntegrationProviderOAuth(
     error?: string | undefined;
     requestUrl: string;
   },
-): Promise<{ redirectTo: string }> {
+): Promise<{ redirectTo: string; exactReturn?: boolean }> {
   const apiBaseUrl = integrationBaseUrl(deps.settings.publicBaseUrl, input.requestUrl);
   const returnBaseUrl = deps.settings.webBaseUrl?.replace(/\/+$/, "") ?? apiBaseUrl;
   let state: ProviderOAuthState | null = null;
+  let exactReturnUrl: string | undefined;
+  let connectOperation: { attemptId: string; operationId: string; inputDigest: string } | undefined;
   try {
     state = readProviderOAuthState(input.state, deps.settings);
+    if (state.connectAttemptId) {
+      const stored = await getConnectAttempt(deps.db, state, state.connectAttemptId);
+      if (
+        stored.attempt.providerId !== state.definitionId ||
+        stored.attempt.ownership !== state.ownership
+      )
+        throw new ProviderOAuthCallbackError("state_invalid");
+      exactReturnUrl = stored.returnUrl;
+      connectOperation = {
+        attemptId: state.connectAttemptId,
+        operationId: `oauth:${state.nonce}`,
+        inputDigest: createHash("sha256").update(input.state!).digest("hex"),
+      };
+      const claim = await claimOAuthAcquisition(
+        deps.db,
+        state,
+        {
+          ...connectOperation,
+          expectedRevision: stored.attempt.revision,
+          authorize: (tx, _attempt, origin) =>
+            requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+        },
+        integrationKeyForConnectProvider(state.definitionId),
+        Boolean(input.code && !input.error),
+      );
+      if (claim.status === "replayed") return { redirectTo: exactReturnUrl, exactReturn: true };
+    }
+    requireProviderOAuthOwner(state);
     await requireProviderOAuthGrant(deps, state);
     const consumed = await consumeIntegrationOAuthStateNonce(deps.db, {
       accountId: state.accountId,
@@ -237,11 +318,31 @@ export async function completeApiIntegrationProviderOAuth(
       now: new Date(),
     });
     if (!consumed) throw new ProviderOAuthCallbackError("state_replayed");
+    if (connectOperation && (input.error || !input.code)) {
+      await finishConnectOperation(deps.db, state, {
+        ...connectOperation,
+        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 ProviderOAuthCallbackError("provider_denied");
     if (!input.code) throw new ProviderOAuthCallbackError("missing_code");
 
     const definition = integrationDefinitionById(state.definitionId);
     if (!definition) throw new ProviderOAuthCallbackError("state_invalid");
+    await withOrganizationIntegrationAcquisition(deps.db, state, [definition.id], async () => {});
     if (
       state.definitionFingerprint !== providerDefinitionFingerprint(definition) ||
       state.providerDomain !== integrationDefinitionProviderDomain(definition) ||
@@ -258,7 +359,7 @@ export async function completeApiIntegrationProviderOAuth(
     }
     const key = requireEnvironmentEncryption(deps.settings);
     const verifier = decryptEnvironmentValue(key, state.encryptedPkceVerifier);
-    const redirectUri = `${apiBaseUrl}${PROVIDER_OAUTH_CALLBACK_PATH}`;
+    const redirectUri = `${apiBaseUrl}${providerOAuthCallbackPath(definition)}`;
     const token = await exchangeProviderAuthorizationCode(deps, definition, client, {
       code: input.code,
       verifier,
@@ -267,7 +368,7 @@ export async function completeApiIntegrationProviderOAuth(
     if (!providerScopesInclude(definition, token.scopes, state.authorizeScopes)) {
       throw new ProviderOAuthCallbackError("scope_not_granted");
     }
-    const grantedScopes = token.scopes.length > 0 ? token.scopes : state.authorizeScopes;
+    let grantedScopes = token.scopes.length > 0 ? token.scopes : state.authorizeScopes;
     const identity = await verifyProviderIdentity(deps, definition, token);
     if (
       state.expectedProviderPrincipalId &&
@@ -307,6 +408,11 @@ export async function completeApiIntegrationProviderOAuth(
     if (!refreshToken) {
       throw new ProviderOAuthCallbackError("refresh_token_missing");
     }
+    // Microsoft omits offline_access from access-token scopes. The new or
+    // previously verified refresh token proves this capability instead.
+    if (definition.provider.id === "microsoft") {
+      grantedScopes = uniqueStrings([...grantedScopes, "offline_access"]);
+    }
     const credentialEncrypted = encryptEnvironmentValue(
       key,
       JSON.stringify({
@@ -339,7 +445,8 @@ export async function completeApiIntegrationProviderOAuth(
       ]),
       verifiedAt: new Date().toISOString(),
     });
-    const connection = await persistProviderOAuthConnection(deps.db, {
+    const persistenceInput: import("@opengeni/db").PersistProviderOAuthConnectionInput = {
+      authorize: (tx: import("@opengeni/db").Database) => requireConnectOwnerAuthority(tx, state!),
       accountId: state.accountId,
       workspaceId: state.workspaceId,
       subjectId: ownerSubjectId,
@@ -362,7 +469,46 @@ export async function completeApiIntegrationProviderOAuth(
             requestedConnectionVersion: state.connectionVersion,
           }
         : {}),
-    });
+    };
+    const persist = (database: import("@opengeni/db").Database) =>
+      persistProviderOAuthConnection(database, persistenceInput);
+    if (connectOperation) {
+      await finishOAuthAcquisition(
+        deps.db,
+        state,
+        {
+          ...connectOperation,
+          authorize: (tx, _attempt, origin) =>
+            requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+          commit: async (tx, current) => {
+            const connection = await persist(tx);
+            if (!connection) throw new ProviderOAuthCallbackError("connection_conflict");
+            return {
+              ...current,
+              revision: current.revision + 1,
+              state: "connected_but_incomplete",
+              credentialsCommitted: true,
+              nextAction: { type: "none" },
+              account: {
+                id: connection.id,
+                providerId: current.providerId,
+                label: identity.displayName ?? identity.email ?? identity.principalId,
+                ownership: current.ownership,
+                status: "connected",
+              },
+            };
+          },
+        },
+        definition.id,
+      );
+      return { redirectTo: exactReturnUrl!, exactReturn: true };
+    }
+    const connection = await withOrganizationIntegrationAcquisition(
+      deps.db,
+      state,
+      [definition.id],
+      persist,
+    );
     if (!connection) throw new ProviderOAuthCallbackError("connection_conflict");
     return {
       redirectTo: providerOAuthReturnUrl(returnBaseUrl, state.returnPath, "success", {
@@ -373,14 +519,19 @@ export async function completeApiIntegrationProviderOAuth(
       }),
     };
   } catch (error) {
+    if (exactReturnUrl !== undefined) return { redirectTo: exactReturnUrl, exactReturn: true };
+    const reason = providerOAuthFailureReason(error);
+    // An unreadable state carries no return path; an authentic but aged one
+    // still names its workspace and is reported as expired.
+    const failure = state ? null : oauthStateFailureReturn(deps.settings, input.state);
     return {
       redirectTo: providerOAuthReturnUrl(
         returnBaseUrl,
-        state?.returnPath ?? "/integrations",
+        state?.returnPath ?? failure!.returnPath,
         "error",
         {
           ...(state?.definitionId ? { definitionId: state.definitionId } : {}),
-          reason: providerOAuthFailureReason(error),
+          reason: failure && reason === "state_invalid" ? failure.reason : reason,
         },
       ),
     };
@@ -393,6 +544,23 @@ function requiredDefinition(id: string): IntegrationDefinition {
   return definition;
 }
 
+/** Configuration readiness only: consent and installation are still separate. */
+export function curatedOAuthReadiness(
+  settings: Settings,
+  definition: IntegrationDefinition,
+): { configured: boolean; ownership: ConnectionOwnership[] } {
+  const ownership: ConnectionOwnership[] = ["workspace", "personal"];
+  try {
+    if (!settings.integrationsEnabled) return { configured: false, ownership };
+    requireEnvironmentEncryption(settings);
+    requireIntegrationsStateSecret(settings);
+    providerClientForDefinition(settings, definition);
+    return { configured: true, ownership };
+  } catch {
+    return { configured: false, ownership };
+  }
+}
+
 function providerClientForDefinition(
   settings: Settings,
   definition: IntegrationDefinition,
@@ -434,6 +602,28 @@ function providerClientForDefinition(
   };
 }
 
+export function isApiIntegrationProviderOAuthState(
+  value: string | undefined,
+  settings: Settings,
+): boolean {
+  try {
+    readProviderOAuthState(value, settings);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function providerOAuthCallbackPath(definition: IntegrationDefinition): string {
+  // Google definitions share the established MCP OAuth callback. The
+  // route distinguishes signed provider state from MCP state, while the
+  // separate google-drive callback remains available for the legacy Drive
+  // installation flow.
+  return definition.provider.id === "google"
+    ? "/v1/integrations/oauth/callback"
+    : PROVIDER_OAUTH_CALLBACK_PATH;
+}
+
 function providerClientKeys(definition: IntegrationDefinition): string[] {
   const authorization = new URL(definition.authentication.authorizationUrl);
   const token = new URL(definition.authentication.tokenUrl);
@@ -500,9 +690,25 @@ function readProviderOAuthState(raw: string | undefined, settings: Settings): Pr
   }
   return {
     accountId: requiredStateString(payload.accountId),
+    ...(optionalString(payload.connectAttemptId)
+      ? { connectAttemptId: optionalString(payload.connectAttemptId)! }
+      : {}),
+    ...(typeof payload.encryptedExternalContinuation === "string"
+      ? {
+          externalContinuation: ExternalActorContinuation.parse(
+            JSON.parse(
+              decryptEnvironmentValue(
+                requireEnvironmentEncryption(settings),
+                payload.encryptedExternalContinuation,
+              ),
+            ),
+          ),
+        }
+      : {}),
     workspaceId: requiredStateString(payload.workspaceId),
     subjectId: requiredStateString(payload.subjectId),
     ownership,
+    personalOwnerVerified: personalOwnerVerifiedInState(payload),
     definitionId: requiredStateString(payload.definitionId),
     definitionFingerprint: requiredStateString(payload.definitionFingerprint),
     providerDomain: requiredStateString(payload.providerDomain),
@@ -645,14 +851,22 @@ async function providerFetch(
 
 async function requireProviderOAuthGrant(
   deps: ApiRouteDeps,
-  state: Pick<ProviderOAuthState, "accountId" | "workspaceId" | "subjectId">,
+  state: Pick<
+    ProviderOAuthState,
+    "accountId" | "workspaceId" | "subjectId" | "personalOwnerVerified" | "externalContinuation"
+  >,
 ): Promise<void> {
-  const grant = await getWorkspaceGrant(deps.db, state.subjectId, state.workspaceId);
-  if (
-    !grant ||
-    grant.accountId !== state.accountId ||
-    !hasPermission(grant.permissions, "connections:write")
-  ) {
+  await deps.db.transaction((tx) => requireConnectOwnerAuthority(tx, state));
+}
+
+/**
+ * A state minted before the start-side principal fence existed can still be in
+ * flight for one `oauthStateTtlMs` window, and it carries no
+ * `personalOwnerVerified` claim. Such a state must not land a personal
+ * Connection.
+ */
+function requireProviderOAuthOwner(state: ProviderOAuthState): void {
+  if (!personalOwnerStateAccepted(state)) {
     throw new ProviderOAuthCallbackError("connection_conflict");
   }
 }
@@ -686,10 +900,24 @@ function providerScopesInclude(
   fallbackScopes: string[],
 ): boolean {
   const effective = returnedScopes.length > 0 ? returnedScopes : fallbackScopes;
-  const normalize = (value: string) =>
-    definition.provider.id === "microsoft" ? value.toLowerCase() : value;
+  const normalize = (value: string) => {
+    if (definition.provider.id === "microsoft") return value.toLowerCase();
+    if (definition.provider.id === "google") {
+      if (value === "email" || value === "https://www.googleapis.com/auth/userinfo.email") {
+        return "email";
+      }
+      if (value === "profile" || value === "https://www.googleapis.com/auth/userinfo.profile") {
+        return "profile";
+      }
+    }
+    return value;
+  };
   const granted = new Set(effective.map(normalize));
-  return definition.authentication.scopes.every((scope) => granted.has(normalize(scope)));
+  return definition.authentication.scopes.every(
+    (scope) =>
+      (definition.provider.id === "microsoft" && normalize(scope) === "offline_access") ||
+      granted.has(normalize(scope)),
+  );
 }
 
 function providerOAuthReturnUrl(