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

package/src/integrations/pr-review-provider.ts

@@ -0,0 +1,246 @@
+import type { PrReviewProvider } from "@opengeni/contracts";
+import {
+  pinnedFetch,
+  readResponseJsonBounded,
+  readResponseTextBounded,
+  type FetchLike,
+  type OutboundNetworkSettings,
+} from "@opengeni/network";
+
+const providerVerificationTimeoutMs = 15_000;
+const providerVerificationResponseMaxBytes = 256 * 1024;
+const providerVerificationErrorMaxBytes = 8 * 1024;
+
+export class PrReviewProviderRepositoryError extends Error {
+  constructor(
+    readonly reason: "denied" | "identity_mismatch" | "unavailable",
+    message: string,
+  ) {
+    super(message);
+    this.name = "PrReviewProviderRepositoryError";
+  }
+}
+
+export type VerifiedPrReviewProviderRepository = {
+  repositoryUri: string;
+  repositoryFullName: string;
+  providerRepositoryId: string;
+  projectId: string;
+};
+
+export async function verifyPrReviewProviderRepository(input: {
+  provider: Exclude<PrReviewProvider, "github">;
+  providerBaseUrl: string;
+  providerRepositoryId: string;
+  projectId?: string;
+  token: string;
+  username: string | null;
+  settings: OutboundNetworkSettings;
+  fetchImpl?: FetchLike;
+}): Promise<VerifiedPrReviewProviderRepository> {
+  return input.provider === "gitlab"
+    ? await verifyGitLabRepository(input)
+    : await verifyAzureDevOpsRepository(input);
+}
+
+async function verifyGitLabRepository(
+  input: Parameters<typeof verifyPrReviewProviderRepository>[0],
+): Promise<VerifiedPrReviewProviderRepository> {
+  if (!/^\d+$/.test(input.providerRepositoryId)) {
+    throw new PrReviewProviderRepositoryError(
+      "identity_mismatch",
+      "GitLab repository bindings require the numeric project ID",
+    );
+  }
+  const url = providerApiUrl(
+    input.providerBaseUrl,
+    `api/v4/projects/${encodeURIComponent(input.providerRepositoryId)}`,
+  );
+  const payload = await providerJson(input, url, {
+    authorization: `Bearer ${input.token}`,
+  });
+  const id = scalarId(payload.id);
+  const fullName = nonEmptyText(payload.path_with_namespace);
+  const repositoryUri = credentialFreeHttps(payload.http_url_to_repo, input.providerBaseUrl);
+  if (id !== input.providerRepositoryId || !fullName || !repositoryUri) {
+    throw new PrReviewProviderRepositoryError(
+      "identity_mismatch",
+      "GitLab returned a different or incomplete project identity",
+    );
+  }
+  return {
+    repositoryUri,
+    repositoryFullName: fullName,
+    providerRepositoryId: id,
+    projectId: id,
+  };
+}
+
+async function verifyAzureDevOpsRepository(
+  input: Parameters<typeof verifyPrReviewProviderRepository>[0],
+): Promise<VerifiedPrReviewProviderRepository> {
+  if (!input.projectId) {
+    throw new PrReviewProviderRepositoryError(
+      "identity_mismatch",
+      "Azure DevOps repository bindings require the exact project ID",
+    );
+  }
+  const url = providerApiUrl(
+    input.providerBaseUrl,
+    `${encodeURIComponent(input.projectId)}/_apis/git/repositories/${encodeURIComponent(input.providerRepositoryId)}`,
+  );
+  url.searchParams.set("api-version", "7.1");
+  const authorization = Buffer.from(`${input.username ?? "pr-review"}:${input.token}`).toString(
+    "base64",
+  );
+  const payload = await providerJson(input, url, {
+    authorization: `Basic ${authorization}`,
+  });
+  const project = record(payload.project);
+  const id = scalarId(payload.id);
+  const projectId = scalarId(project?.id);
+  const repositoryName = nonEmptyText(payload.name);
+  const projectName = nonEmptyText(project?.name);
+  const repositoryUri = credentialFreeHttps(payload.remoteUrl, input.providerBaseUrl);
+  if (
+    !id ||
+    id.toLowerCase() !== input.providerRepositoryId.toLowerCase() ||
+    !projectId ||
+    projectId.toLowerCase() !== input.projectId.toLowerCase() ||
+    !repositoryName ||
+    !repositoryUri
+  ) {
+    throw new PrReviewProviderRepositoryError(
+      "identity_mismatch",
+      "Azure DevOps returned a different or incomplete repository identity",
+    );
+  }
+  return {
+    repositoryUri,
+    repositoryFullName: projectName ? `${projectName}/${repositoryName}` : repositoryName,
+    providerRepositoryId: id,
+    projectId,
+  };
+}
+
+async function providerJson(
+  input: Parameters<typeof verifyPrReviewProviderRepository>[0],
+  url: URL,
+  headers: Record<string, string>,
+): Promise<Record<string, unknown>> {
+  const signal = AbortSignal.timeout(providerVerificationTimeoutMs);
+  let response: Response;
+  try {
+    const requestInit = {
+      headers: { accept: "application/json", ...headers },
+      signal,
+    } satisfies RequestInit;
+    response = input.fetchImpl
+      ? await input.fetchImpl(url, requestInit)
+      : await pinnedFetch(url, requestInit, input.settings, {
+          label: `${input.provider} PR Review repository verification`,
+          requireHttpsOutsideLocalTest: true,
+        });
+  } catch {
+    throw new PrReviewProviderRepositoryError(
+      "unavailable",
+      `${input.provider} repository verification is unavailable`,
+    );
+  }
+  if (response.status === 401 || response.status === 403 || response.status === 404) {
+    await readResponseTextBounded(
+      response,
+      providerVerificationErrorMaxBytes,
+      `${input.provider} repository verification error`,
+      { signal },
+    ).catch(() => undefined);
+    throw new PrReviewProviderRepositoryError(
+      "denied",
+      `${input.provider} credential cannot access the requested repository`,
+    );
+  }
+  if (!response.ok) {
+    await readResponseTextBounded(
+      response,
+      providerVerificationErrorMaxBytes,
+      `${input.provider} repository verification error`,
+      { signal },
+    ).catch(() => undefined);
+    throw new PrReviewProviderRepositoryError(
+      "unavailable",
+      `${input.provider} repository verification failed`,
+    );
+  }
+  let payload: unknown;
+  try {
+    payload = await readResponseJsonBounded(
+      response,
+      providerVerificationResponseMaxBytes,
+      `${input.provider} repository metadata`,
+      { signal },
+    );
+  } catch {
+    throw new PrReviewProviderRepositoryError(
+      "unavailable",
+      `${input.provider} returned invalid repository metadata`,
+    );
+  }
+  const parsed = record(payload);
+  if (!parsed) {
+    throw new PrReviewProviderRepositoryError(
+      "unavailable",
+      `${input.provider} returned invalid repository metadata`,
+    );
+  }
+  return parsed;
+}
+
+function providerApiUrl(base: string, suffix: string): URL {
+  const url = new URL(base);
+  url.pathname = `${url.pathname.replace(/\/+$/, "")}/${suffix}`;
+  url.search = "";
+  url.hash = "";
+  return url;
+}
+
+function credentialFreeHttps(value: unknown, providerBaseUrl: string): string | null {
+  if (typeof value !== "string") return null;
+  let candidate: URL;
+  const provider = new URL(providerBaseUrl);
+  try {
+    candidate = new URL(value);
+  } catch {
+    return null;
+  }
+  const providerPath = provider.pathname.replace(/\/+$/, "");
+  if (
+    candidate.protocol !== "https:" ||
+    candidate.username ||
+    candidate.password ||
+    candidate.href.length > 2048 ||
+    candidate.host.toLowerCase() !== provider.host.toLowerCase() ||
+    (providerPath !== "" &&
+      providerPath !== "/" &&
+      candidate.pathname !== providerPath &&
+      !candidate.pathname.startsWith(`${providerPath}/`))
+  ) {
+    return null;
+  }
+  return candidate.href;
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function scalarId(value: unknown): string | null {
+  if (typeof value === "string" && value.length > 0 && value.length <= 512) return value;
+  if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) return String(value);
+  return null;
+}
+
+function nonEmptyText(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 && value.length <= 1024 ? value : null;
+}

package/src/integrations/provider-oauth.ts

@@ -37,11 +37,23 @@ import {
 } from "@opengeni/network";
 import { HTTPException } from "hono/http-exception";
 
+import {
+  assertConnectionOwnershipAllowedForPrincipal,
+  personalOwnerStateAccepted,
+  personalOwnerVerifiedInState,
+  PERSONAL_OWNER_VERIFIED_STATE_CLAIM,
+} from "../connection-ownership";
 import {
   integrationBaseUrl,
   oauthStateTtlMs,
   requireIntegrationsStateSecret,
 } from "./oauth-client";
+import {
+  assertOwnershipAllowed,
+  builtInOAuthProfileFor,
+  DEFAULT_OAUTH_PROFILE,
+  type OAuthProviderProfile,
+} from "./oauth-profiles";
 
 const PROVIDER_OAUTH_CALLBACK_PATH = "/v1/integrations/provider-oauth/callback";
 const PROVIDER_OAUTH_TIMEOUT_MS = 15_000;
@@ -60,6 +72,7 @@ type ProviderOAuthState = {
   workspaceId: string;
   subjectId: string;
   ownership: ConnectionOwnership;
+  personalOwnerVerified: boolean;
   definitionId: string;
   definitionFingerprint: string;
   providerDomain: string;
@@ -117,6 +130,12 @@ 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;
     requestUrl: string;
     payload: ApiIntegrationOAuthStartRequest;
   },
@@ -155,7 +174,33 @@ export async function startApiIntegrationProviderOAuth(
       message: "The selected Connection ownership does not match this OAuth request",
     });
   }
-  const ownership = existingOwnership ?? input.payload.ownership ?? "personal";
+  // This flow used to resolve an omitted ownership to `personal`, inverting the
+  // documented workspace-owned default. Resolving it to `workspace` instead
+  // would have been the opposite defect: an executed probe on
+  // `microsoft-outlook-mail` confirmed it flips a newly connected mailbox from
+  // subject-scoped to workspace-shared for API/SDK callers, which is a real
+  // narrow -> broad widening. So an ambiguous omission is refused outright and
+  // the caller must choose. A profile that allows exactly one ownership is not
+  // ambiguous (Gmail and hosted Slack MCP are personal-only), and a reconnect
+  // takes the existing row's ownership.
+  const profile = providerOAuthProfile(definition, providerDomain);
+  const ownership =
+    existingOwnership ?? input.payload.ownership ?? soleAllowedOwnership(profile) ?? 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',
+    });
+  }
+  // Inert by construction today, and deliberately kept: no curated Definition
+  // resolves to a personal-only profile (all five are Google Workspace and
+  // Microsoft Graph APIs, so `providerOAuthProfile` returns the default), which
+  // is why disabling this line reddens nothing. It is the fence that keeps a
+  // future Definition targeting slack.com or Gmail from minting an ownership
+  // its profile forbids - read it as pre-wiring, not as an untested gap.
+  assertOwnershipAllowed(profile, ownership);
+  assertConnectionOwnershipAllowedForPrincipal(ownership, input.personalOwnershipAllowed);
   const authorizeScopes = uniqueStrings([
     ...(existing?.grantedScopes ?? []),
     ...definition.authentication.scopes,
@@ -164,7 +209,7 @@ 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`,
   );
@@ -173,6 +218,9 @@ export async function startApiIntegrationProviderOAuth(
     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,
@@ -227,6 +275,7 @@ export async function completeApiIntegrationProviderOAuth(
   let state: ProviderOAuthState | null = null;
   try {
     state = readProviderOAuthState(input.state, deps.settings);
+    requireProviderOAuthOwner(state);
     await requireProviderOAuthGrant(deps, state);
     const consumed = await consumeIntegrationOAuthStateNonce(deps.db, {
       accountId: state.accountId,
@@ -258,7 +307,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,
@@ -387,6 +436,28 @@ export async function completeApiIntegrationProviderOAuth(
   }
 }
 
+/**
+ * The ownership fences that apply to a curated Definition, read from the same
+ * profile table the MCP OAuth start uses. No curated Definition targets a
+ * personal-only provider today (they are Google Workspace and Microsoft Graph
+ * APIs), so this resolves to the default profile and its workspace default;
+ * matching by provider domain keeps the Slack/Gmail fences in force if one ever
+ * does, instead of letting this flow mint an ownership their profile forbids.
+ */
+/** The profile's ownership when it allows exactly one, else null (ambiguous). */
+function soleAllowedOwnership(profile: OAuthProviderProfile): ConnectionOwnership | null {
+  return profile.allowedOwnership.length === 1 ? profile.allowedOwnership[0]! : null;
+}
+
+function providerOAuthProfile(
+  definition: IntegrationDefinition,
+  providerDomain: string,
+): OAuthProviderProfile {
+  return (
+    builtInOAuthProfileFor({ mcpUrl: definition.baseUrl, providerDomain }) ?? DEFAULT_OAUTH_PROFILE
+  );
+}
+
 function requiredDefinition(id: string): IntegrationDefinition {
   const definition = integrationDefinitionById(id);
   if (!definition) throw new HTTPException(404, { message: "Unknown Integration definition" });
@@ -434,6 +505,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);
@@ -503,6 +596,7 @@ function readProviderOAuthState(raw: string | undefined, settings: Settings): Pr
     workspaceId: requiredStateString(payload.workspaceId),
     subjectId: requiredStateString(payload.subjectId),
     ownership,
+    personalOwnerVerified: personalOwnerVerifiedInState(payload),
     definitionId: requiredStateString(payload.definitionId),
     definitionFingerprint: requiredStateString(payload.definitionFingerprint),
     providerDomain: requiredStateString(payload.providerDomain),
@@ -657,6 +751,18 @@ async function requireProviderOAuthGrant(
   }
 }
 
+/**
+ * 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");
+  }
+}
+
 function requireProviderOAuthConnection(
   connection: NonNullable<Awaited<ReturnType<typeof getConnectionMetadata>>>,
   input: {
@@ -686,8 +792,18 @@ 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)));
 }