@opengeni/api-router 3.0.1 → 3.1.2

package/src/integrations/oauth-profiles.ts

@@ -1,7 +1,17 @@
+import {
+  normalizeSlackScopes,
+  OPENGENI_SLACK_REST_USER_SCOPES,
+  slackRestMcpToolsForScopes,
+} from "@opengeni/contracts/slack-rest-mcp";
 import { OPENGENI_PERSONAL_SLACK_MCP_URL, type ConnectionOwnership } from "@opengeni/contracts";
 import type { Settings } from "@opengeni/config";
 import { HTTPException } from "hono/http-exception";
 import { z } from "zod";
+import {
+  GMAIL_REST_MCP_TOOLS,
+  gmailToolAvailableOnDeployment,
+  gmailToolSupportsScopes,
+} from "@opengeni/runtime/gmail-rest-mcp";
 import { canonicalProviderDomain } from "./provider-domain";
 
 /**
@@ -16,10 +26,9 @@ import { canonicalProviderDomain } from "./provider-domain";
  *
  * Profiles come from two layers:
  *
- * 1. Built-in profiles below, for the providers whose fences are security
- *    invariants (hosted Slack MCP and official Gmail are personal-only, their
- *    authorization servers are origin-pinned). These live in code as data so
- *    the fences never depend on catalog import state.
+ * 1. Built-in profiles pin known authorization servers and protocol quirks.
+ *    Ownership defaults guide setup; users may choose personal or workspace.
+ *    Authorization-server pins never depend on catalog import state.
  * 2. A validated `oauthProfile` object on a global catalog row (curated
  *    overlay -> importer -> `capability_catalog_items.metadata`). A catalog
  *    profile applies only when no built-in matches, and it can only narrow the
@@ -81,10 +90,10 @@ export type OAuthProviderProfile = {
   requireExactMcpUrl?: { url: string; message: string };
   /** Deployment-managed client credentials must be configured (503 otherwise). */
   requireDeploymentClient?: { key: DeploymentManagedClientKey; message: string };
-  /** Ownerships a connection may take; a singleton also sets the default. */
-  allowedOwnership: readonly ConnectionOwnership[];
-  /** Exact 422 message when an explicit disallowed ownership is requested. */
-  ownershipMessage?: string;
+  /** Suggested ownership; explicit choices remain subject to requiredOwnership. */
+  defaultOwnership?: ConnectionOwnership;
+  /** Built-in-only ownership restriction, including old reconnect/callback state. */
+  requiredOwnership?: { ownership: ConnectionOwnership; message: string };
   /** Bind reconnect/dedupe to the exact mcpUrl, not just the provider domain. */
   exactMcpBinding: boolean;
   /** How an existing connection is chosen for reconnect coalescing. */
@@ -108,12 +117,35 @@ export type OAuthProviderProfile = {
   extraAuthorizeParams?: Readonly<Record<string, string>>;
   /** Exact scope override; the caller can never widen past it. */
   requestedScopes?: readonly string[];
+  /** Reviewed local bridge grant normalization and token verification. Catalog profiles cannot supply code. */
+  normalizeGrantedScopes?: (scopes: readonly string[] | string) => string[];
+  reportedScopesRequired?: boolean;
+  /** Built-in durable API bridges may refuse a new grant without offline access. */
+  freshRefreshTokenRequired?: boolean;
+  /** The reviewed bridge exposes one tool contract, not a partial-scope variant. */
+  fullRequestedScopesRequired?: boolean;
+  /** Built-in web OAuth clients must use a configured secret and provider-supported authentication. */
+  confidentialClientRequired?: boolean;
+  /** Built-in API bridge discovery; catalog metadata cannot redirect this seam. */
+  providerOAuthDiscovery?: { issuer: string; metadataUrl: string };
+  localToolVerification?: {
+    url: string;
+    method?: "GET" | "POST";
+    /** An API bridge may require a verified account before accepting a grant. */
+    required?: boolean;
+    /** Distinguish a rejected OAuth grant from a temporary verification failure. */
+    isRejectedGrant?: (payload: Record<string, unknown>) => boolean;
+    validateIdentity: (payload: Record<string, unknown>) => Record<string, string>;
+    toolsForScopes: (
+      scopes: readonly string[],
+      deployment: { gmailWatchTopicName?: string | undefined },
+    ) => Array<{ name: string; description?: string }>;
+  };
 };
 
 export const DEFAULT_OAUTH_PROFILE: OAuthProviderProfile = {
   key: "default",
   match: {},
-  allowedOwnership: ["workspace", "personal"],
   exactMcpBinding: false,
   connectionSelection: "first_active",
   sendResourceParameter: true,
@@ -138,9 +170,6 @@ const HOSTED_SLACK_PROFILE: OAuthProviderProfile = {
     key: "slack",
     message: "Slack MCP OAuth requires OPENGENI_SLACK_CLIENT_ID and OPENGENI_SLACK_CLIENT_SECRET",
   },
-  allowedOwnership: ["personal"],
-  ownershipMessage:
-    "Slack's hosted MCP connection is personal only; install the OpenGeni Slack bot for workspace access",
   exactMcpBinding: true,
   connectionSelection: "canonical_personal",
   authorizationServer: {
@@ -151,14 +180,51 @@ const HOSTED_SLACK_PROFILE: OAuthProviderProfile = {
     skipInLocalTest: true,
   },
   sendResourceParameter: true,
+  requestedScopes: OPENGENI_SLACK_REST_USER_SCOPES,
+  normalizeGrantedScopes: normalizeSlackScopes,
+  reportedScopesRequired: true,
+  localToolVerification: {
+    url: "https://slack.com/api/auth.test",
+    isRejectedGrant: (payload) =>
+      payload.ok === false &&
+      ["invalid_auth", "not_authed", "token_revoked", "account_inactive", "token_expired"].includes(
+        typeof payload.error === "string" ? payload.error : "",
+      ),
+    validateIdentity: (payload) => {
+      if (
+        payload.ok !== true ||
+        typeof payload.team_id !== "string" ||
+        !payload.team_id ||
+        typeof payload.user_id !== "string" ||
+        !payload.user_id ||
+        payload.bot_id
+      ) {
+        throw new Error("Slack account verification failed");
+      }
+      return {
+        slackTeamId: payload.team_id,
+        slackUserId: payload.user_id,
+        ...(typeof payload.team === "string" && payload.team.trim()
+          ? { slackTeamName: payload.team }
+          : {}),
+        ...(typeof payload.user === "string" && payload.user.trim()
+          ? { slackUserName: payload.user }
+          : {}),
+      };
+    },
+    toolsForScopes: slackRestMcpToolsForScopes,
+  },
 };
 
 const OFFICIAL_GMAIL_PROFILE: OAuthProviderProfile = {
   key: "official-gmail",
   match: { mcpUrls: [OFFICIAL_GMAIL_MCP_URL] },
-  allowedOwnership: ["personal"],
-  ownershipMessage:
-    "Gmail connections are personal only; each workspace member must connect their own mailbox",
+  requireExactMcpUrl: {
+    url: OFFICIAL_GMAIL_MCP_URL,
+    message: `Gmail OAuth must use ${OFFICIAL_GMAIL_MCP_URL}`,
+  },
+  defaultOwnership: "personal",
+  requiredOwnership: { ownership: "personal", message: "Gmail connections must be personal-owned" },
   exactMcpBinding: true,
   connectionSelection: "first_active",
   authorizationServer: {
@@ -185,6 +251,37 @@ const OFFICIAL_GMAIL_PROFILE: OAuthProviderProfile = {
   // The Gmail PRM advertises broader grants, including full-mail access. The
   // reviewed connector never lets a caller widen the capability contract.
   requestedScopes: OFFICIAL_GMAIL_MCP_SCOPES,
+  reportedScopesRequired: true,
+  freshRefreshTokenRequired: true,
+  fullRequestedScopesRequired: true,
+  confidentialClientRequired: true,
+  providerOAuthDiscovery: {
+    issuer: GOOGLE_OAUTH_ISSUER_ORIGIN,
+    metadataUrl: `${GOOGLE_OAUTH_ISSUER_ORIGIN}/.well-known/openid-configuration`,
+  },
+  localToolVerification: {
+    url: "https://gmail.googleapis.com/gmail/v1/users/me/profile",
+    method: "GET",
+    required: true,
+    validateIdentity: (payload) => {
+      if (
+        typeof payload.emailAddress !== "string" ||
+        !/^[^\s@]+@[^\s@]+$/u.test(payload.emailAddress)
+      ) {
+        throw new Error("Gmail account verification failed");
+      }
+      return { gmailEmail: payload.emailAddress };
+    },
+    toolsForScopes: (scopes, deployment) => {
+      return GMAIL_REST_MCP_TOOLS.filter(
+        (tool) =>
+          gmailToolSupportsScopes(tool.name, scopes) &&
+          gmailToolAvailableOnDeployment(tool.name, {
+            watchTopicName: deployment.gmailWatchTopicName,
+          }),
+      ).map(({ name, description }) => ({ name, ...(description ? { description } : {}) }));
+    },
+  },
 };
 
 const BUILT_IN_OAUTH_PROFILES: readonly OAuthProviderProfile[] = [
@@ -285,24 +382,7 @@ export function builtInOAuthProfileFor(input: {
 
 /** Ownership an omitted request defaults to under a profile. */
 export function defaultOwnershipFor(profile: OAuthProviderProfile): ConnectionOwnership {
-  return profile.allowedOwnership.length === 1 && profile.allowedOwnership[0] === "personal"
-    ? "personal"
-    : "workspace";
-}
-
-/** Rejects an ownership outside the profile's allowed set with its exact message. */
-export function assertOwnershipAllowed(
-  profile: OAuthProviderProfile,
-  ownership: ConnectionOwnership,
-): void {
-  if (profile.allowedOwnership.includes(ownership)) {
-    return;
-  }
-  throw new HTTPException(422, {
-    message:
-      profile.ownershipMessage ??
-      `this integration allows only ${profile.allowedOwnership.join(" or ")} connections`,
-  });
+  return profile.defaultOwnership ?? "workspace";
 }
 
 /** Enforces a profile's authorization-server origin pins with its exact message. */
@@ -375,10 +455,7 @@ export const catalogOAuthProfileSchema = z
     pinnedIssuerOrigins: z.array(z.string().url()).min(1).optional(),
     pinnedEndpointOrigins: z.array(z.string().url()).min(1).optional(),
     sendResourceParameter: z.boolean().optional(),
-    allowedOwnership: z
-      .array(z.enum(["personal", "workspace"]))
-      .min(1)
-      .optional(),
+    defaultOwnership: z.enum(["personal", "workspace"]).optional(),
     requestedScopes: z.array(z.string().min(1)).min(1).optional(),
     extraAuthorizeParams: z
       .record(z.string(), z.string())
@@ -425,7 +502,7 @@ export function catalogMcpUrlKey(value: string): string {
  *
  * A present-but-invalid profile fails closed with a 422: the row's operator
  * declared constraints, and silently degrading to the default profile would
- * drop an ownership fence or origin pin on a JSON typo.
+ * drop an origin pin on a JSON typo.
  */
 export function oauthProfileFromCatalog(mcpUrl: string, raw: unknown): OAuthProviderProfile {
   const parsed = catalogOAuthProfileSchema.safeParse(raw);
@@ -451,13 +528,7 @@ export function oauthProfileFromCatalog(mcpUrl: string, raw: unknown): OAuthProv
   return {
     key: `catalog:${mcpUrl}`,
     match: { mcpUrls: [mcpUrl] },
-    allowedOwnership: data.allowedOwnership ?? DEFAULT_OAUTH_PROFILE.allowedOwnership,
-    ...(data.allowedOwnership && !data.allowedOwnership.includes("workspace")
-      ? {
-          ownershipMessage:
-            "this integration allows only personal connections; each workspace member must connect their own account",
-        }
-      : {}),
+    ...(data.defaultOwnership ? { defaultOwnership: data.defaultOwnership } : {}),
     exactMcpBinding: Boolean(data.exactMcpUrl),
     ...(data.exactMcpUrl
       ? {

package/src/integrations/onepassword-vault-provider.ts

@@ -0,0 +1,16 @@
+import type { OnePasswordVaultProviderFactory } from "@opengeni/core";
+
+/**
+ * Loads the 1Password adapter (and its ~14 MB WASM SDK) only when a request
+ * first touches 1Password. The only allowed import edge, besides apps/worker,
+ * is this dynamic one (OP-5, packages/vaults-onepassword/test/import-guard.test.ts).
+ */
+export const loadOnePasswordVaultProvider: OnePasswordVaultProviderFactory = async (input) => {
+  const { vaultProviderForOnePasswordConnection } = await import("@opengeni/vaults-onepassword");
+  return vaultProviderForOnePasswordConnection(input);
+};
+
+/** The offline token check and connection-scoped provider used by the install route. */
+export async function loadOnePasswordModule() {
+  return await import("@opengeni/vaults-onepassword");
+}

package/src/integrations/personal-github-repositories.ts

@@ -592,7 +592,7 @@ async function personalGitHubProviderFetch(
       headers: {
         accept: "application/vnd.github+json",
         authorization,
-        "user-agent": "OpenGeni",
+        "user-agent": "Opengeni",
         "x-github-api-version": GITHUB_API_VERSION,
       },
       signal: AbortSignal.timeout(GITHUB_REQUEST_TIMEOUT_MS),

package/src/integrations/personal-github.ts

@@ -1,3 +1,5 @@
+import { withOrganizationIntegrationAcquisition } from "@opengeni/db/organization-integration-policy";
+import { claimOAuthAcquisition, finishOAuthAcquisition } from "./oauth-client";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
 import { requireConnectOwnerAuthority } from "./connect-authority";
@@ -23,7 +25,6 @@ import {
 } from "@opengeni/core";
 import {
   consumeIntegrationOAuthStateNonce,
-  claimConnectOperation,
   finishConnectOperation,
   getConnectAttempt,
   type Database,
@@ -47,8 +48,10 @@ import {
 } from "../connection-ownership";
 import {
   integrationBaseUrl,
+  oauthStateFailureReturn,
   oauthStateTtlMs,
   requireIntegrationsStateSecret,
+  workspaceIntegrationsPath,
 } from "./oauth-client";
 
 const PERSONAL_GITHUB_OAUTH_STATE_KIND = "personal_github_oauth";
@@ -216,6 +219,7 @@ export async function startPersonalGitHubOAuth(
 ) {
   const oauth = requirePersonalGitHubOAuthSettings(deps.settings);
   const { grant } = input.access;
+  await withOrganizationIntegrationAcquisition(deps.db, grant, ["github-personal"], async () => {});
   const existing = input.connectionId
     ? await getConnectionMetadata(deps.db, input.workspaceId, input.connectionId, grant.subjectId)
     : null;
@@ -301,12 +305,18 @@ export async function completePersonalGitHubOAuthCallback(
         operationId: `oauth:${state.nonce}`,
         inputDigest: createHash("sha256").update(input.state!).digest("hex"),
       };
-      const claim = await claimConnectOperation(deps.db, state, {
-        ...operation,
-        expectedRevision: stored.attempt.revision,
-        authorize: (tx, _attempt, origin) =>
-          requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
-      });
+      const claim = await claimOAuthAcquisition(
+        deps.db,
+        state,
+        {
+          ...operation,
+          expectedRevision: stored.attempt.revision,
+          authorize: (tx, _attempt, origin) =>
+            requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
+        },
+        "github-personal",
+        Boolean(input.code && !input.error),
+      );
       if (claim.status === "replayed") return { redirectTo: exactReturnUrl, exactReturn: true };
     }
     await requirePersonalGitHubCallbackGrant(deps, state);
@@ -340,6 +350,12 @@ export async function completePersonalGitHubOAuthCallback(
     }
     if (input.error) throw new PersonalGitHubCallbackError("provider_denied");
     if (!input.code) throw new PersonalGitHubCallbackError("missing_code");
+    await withOrganizationIntegrationAcquisition(
+      deps.db,
+      state,
+      ["github-personal"],
+      async () => {},
+    );
 
     const oauth = requirePersonalGitHubOAuthSettings(deps.settings);
     if (
@@ -474,33 +490,43 @@ export async function completePersonalGitHubOAuthCallback(
       });
     };
     if (operation) {
-      await finishConnectOperation(deps.db, acceptedState, {
-        ...operation,
-        authorize: (tx, _attempt, origin) =>
-          requireConnectOwnerAuthority(tx, acceptedState, "connections:write", origin),
-        commit: async (tx, current) => {
-          const connection = await persist(tx);
-          if (!connection) throw new PersonalGitHubCallbackError("connection_conflict");
-          return {
-            ...current,
-            revision: current.revision + 1,
-            state: "complete",
-            credentialsCommitted: true,
-            nextAction: { type: "none" },
-            account: {
-              id: connection.id,
-              version: connection.version,
-              providerId: "github-personal",
-              label: identity.login,
-              ownership: "personal",
-              status: "connected",
-            },
-          };
+      await finishOAuthAcquisition(
+        deps.db,
+        acceptedState,
+        {
+          ...operation,
+          authorize: (tx, _attempt, origin) =>
+            requireConnectOwnerAuthority(tx, acceptedState, "connections:write", origin),
+          commit: async (tx, current) => {
+            const connection = await persist(tx);
+            if (!connection) throw new PersonalGitHubCallbackError("connection_conflict");
+            return {
+              ...current,
+              revision: current.revision + 1,
+              state: "complete",
+              credentialsCommitted: true,
+              nextAction: { type: "none" },
+              account: {
+                id: connection.id,
+                version: connection.version,
+                providerId: "github-personal",
+                label: identity.login,
+                ownership: "personal",
+                status: "connected",
+              },
+            };
+          },
         },
-      });
+        "github-personal",
+      );
       return { redirectTo: exactReturnUrl!, exactReturn: true };
     }
-    const connection = await persist(deps.db);
+    const connection = await withOrganizationIntegrationAcquisition(
+      deps.db,
+      acceptedState,
+      ["github-personal"],
+      persist,
+    );
     if (!connection) throw new PersonalGitHubCallbackError("connection_conflict");
     return {
       redirectTo: personalGitHubCallbackReturnUrl(returnBaseUrl, state.returnPath, "success", {
@@ -512,7 +538,7 @@ export async function completePersonalGitHubOAuthCallback(
     return {
       redirectTo: personalGitHubCallbackReturnUrl(
         returnBaseUrl,
-        state?.returnPath ?? "/integrations",
+        state?.returnPath ?? oauthStateFailureReturn(deps.settings, input.state).returnPath,
         "error",
         { reason: personalGitHubFailureReason(error) },
       ),
@@ -620,7 +646,7 @@ async function exchangePersonalGitHubAuthorizationCode(
       headers: {
         accept: "application/json",
         "content-type": "application/x-www-form-urlencoded",
-        "user-agent": "OpenGeni",
+        "user-agent": "Opengeni",
       },
       body: new URLSearchParams({
         client_id: oauth.clientId,
@@ -679,7 +705,7 @@ async function fetchPersonalGitHubIdentity(
       headers: {
         accept: "application/vnd.github+json",
         authorization: `Bearer ${accessToken}`,
-        "user-agent": "OpenGeni",
+        "user-agent": "Opengeni",
         "x-github-api-version": GITHUB_API_VERSION,
       },
       signal: AbortSignal.timeout(GITHUB_REQUEST_TIMEOUT_MS),
@@ -728,7 +754,7 @@ function parseGitHubScopes(raw: string | null): string[] {
 }
 
 function personalGitHubReturnPath(workspaceId: string, raw?: string): string {
-  const fallback = `/workspaces/${workspaceId}/capabilities`;
+  const fallback = workspaceIntegrationsPath(workspaceId);
   if (!raw) return fallback;
   let parsed: URL;
   try {