@opengeni/api-router 3.0.1 → 4.0.0

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,
@@ -216,6 +217,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 +303,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 +348,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 +488,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", {

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,7 +20,11 @@ import {
   type ApiIntegrationOAuthStartRequest,
   type ConnectionOwnership,
 } from "@opengeni/contracts";
-import { requireEnvironmentEncryption, type ApiRouteDeps } from "@opengeni/core";
+import {
+  integrationKeyForConnectProvider,
+  requireEnvironmentEncryption,
+  type ApiRouteDeps,
+} from "@opengeni/core";
 import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
 import {
   consumeIntegrationOAuthStateNonce,
@@ -28,7 +34,6 @@ import {
   loadConnectionCredentialForBroker,
   persistProviderOAuthConnection,
   getConnectAttempt,
-  claimConnectOperation,
   finishConnectOperation,
 } from "@opengeni/db";
 import { createSignedState, readSignedState } from "@opengeni/github";
@@ -52,12 +57,6 @@ import {
   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;
@@ -149,6 +148,7 @@ export async function startApiIntegrationProviderOAuth(
   },
 ): 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(
@@ -182,18 +182,8 @@ export async function startApiIntegrationProviderOAuth(
       message: "The selected Connection ownership does not match this OAuth request",
     });
   }
-  // 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;
+  // 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:
@@ -201,13 +191,6 @@ export async function startApiIntegrationProviderOAuth(
         '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 ?? []),
@@ -307,12 +290,18 @@ export async function completeApiIntegrationProviderOAuth(
         operationId: `oauth:${state.nonce}`,
         inputDigest: createHash("sha256").update(input.state!).digest("hex"),
       };
-      const claim = await claimConnectOperation(deps.db, state, {
-        ...connectOperation,
-        expectedRevision: stored.attempt.revision,
-        authorize: (tx, _attempt, origin) =>
-          requireConnectOwnerAuthority(tx, state!, "connections:write", origin),
-      });
+      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);
@@ -350,6 +339,7 @@ export async function completeApiIntegrationProviderOAuth(
 
     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) ||
@@ -480,32 +470,42 @@ export async function completeApiIntegrationProviderOAuth(
     const persist = (database: import("@opengeni/db").Database) =>
       persistProviderOAuthConnection(database, persistenceInput);
     if (connectOperation) {
-      await finishConnectOperation(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",
-            },
-          };
+      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 persist(deps.db);
+    const connection = await withOrganizationIntegrationAcquisition(
+      deps.db,
+      state,
+      [definition.id],
+      persist,
+    );
     if (!connection) throw new ProviderOAuthCallbackError("connection_conflict");
     return {
       redirectTo: providerOAuthReturnUrl(returnBaseUrl, state.returnPath, "success", {
@@ -531,28 +531,6 @@ 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" });
@@ -564,10 +542,7 @@ export function curatedOAuthReadiness(
   settings: Settings,
   definition: IntegrationDefinition,
 ): { configured: boolean; ownership: ConnectionOwnership[] } {
-  const ownership = [
-    ...providerOAuthProfile(definition, integrationDefinitionProviderDomain(definition))
-      .allowedOwnership,
-  ];
+  const ownership: ConnectionOwnership[] = ["workspace", "personal"];
   try {
     if (!settings.integrationsEnabled) return { configured: false, ownership };
     requireEnvironmentEncryption(settings);

package/src/integrations/social-oauth.ts

@@ -1,3 +1,5 @@
+import { withOrganizationIntegrationAcquisition } from "@opengeni/db/organization-integration-policy";
+import { claimOAuthAcquisition, finishOAuthAcquisition } from "./oauth-client";
 import { parseSocialOauthClientsJson, type Settings } from "@opengeni/config";
 import {
   OAuthStartResponse,
@@ -15,7 +17,6 @@ import {
   loadSocialConnectionCredential,
   updateSocialConnectionCredential,
   upsertSocialOAuthConnection,
-  claimConnectOperation,
   finishConnectOperation,
   getConnectAttempt,
   type Database,
@@ -196,6 +197,7 @@ export async function startSocialOAuth(
 ): Promise<OAuthStartResponse> {
   const { settings } = deps;
   const provider = SOCIAL_OAUTH_PROVIDERS[context.payload.provider];
+  await withOrganizationIntegrationAcquisition(deps.db, context, [provider.id], async () => {});
   const client = socialOAuthClientFor(settings, provider.id);
   const redirectUri = socialOAuthRedirectUri(settings, context.requestUrl);
   const returnPath = safeReturnPath(context.payload.returnPath ?? "/integrations");
@@ -323,6 +325,7 @@ export async function completeSocialOAuthCallback(
   }
   try {
     const provider = SOCIAL_OAUTH_PROVIDERS[state.provider];
+    await withOrganizationIntegrationAcquisition(db, state, [provider.id], async () => {});
     const client = socialOAuthClientFor(settings, provider.id);
     const key = requireEnvironmentEncryption(settings);
     const verifier = state.encryptedPkceVerifier
@@ -344,18 +347,31 @@ export async function completeSocialOAuthCallback(
       ...(token.scope ? { scope: token.scope } : {}),
     };
     const grantedScopes = token.scope ? token.scope.split(/[\s,]+/).filter(Boolean) : state.scopes;
-    const connection = await upsertSocialOAuthConnection(db, {
-      accountId: state.accountId,
-      workspaceId: state.workspaceId,
-      subjectId: state.ownership === "personal" ? state.subjectId : null,
-      provider: provider.id,
-      accountHandle: identity.handle,
-      accountName: identity.name ?? null,
-      externalAccountId: identity.externalAccountId,
-      scopes: grantedScopes,
-      credentialEncrypted: encryptEnvironmentValue(key, JSON.stringify(bundle)),
-      tokenMetadata: publicTokenMetadata(bundle),
-    });
+    const acceptedState = state;
+    const connection = await withOrganizationIntegrationAcquisition(
+      db,
+      acceptedState,
+      [provider.id],
+      async (tx) => {
+        await requireConnectOwnerAuthority(
+          tx,
+          acceptedState,
+          acceptedState.ownership === "workspace" ? "workspace:admin" : "workspace:read",
+        );
+        return upsertSocialOAuthConnection(tx, {
+          accountId: acceptedState.accountId,
+          workspaceId: acceptedState.workspaceId,
+          subjectId: acceptedState.ownership === "personal" ? acceptedState.subjectId : null,
+          provider: provider.id,
+          accountHandle: identity.handle,
+          accountName: identity.name ?? null,
+          externalAccountId: identity.externalAccountId,
+          scopes: grantedScopes,
+          credentialEncrypted: encryptEnvironmentValue(key, JSON.stringify(bundle)),
+          tokenMetadata: publicTokenMetadata(bundle),
+        });
+      },
+    );
     return {
       redirectTo: callbackReturnPath(state.returnPath, "success", {
         connectionId: connection.id,
@@ -407,10 +423,16 @@ async function completeSocialConnect(
     authorize,
   };
   try {
-    const claim = await claimConnectOperation(deps.db, state, {
-      ...operation,
-      expectedRevision: stored.attempt.revision,
-    });
+    const claim = await claimOAuthAcquisition(
+      deps.db,
+      state,
+      {
+        ...operation,
+        expectedRevision: stored.attempt.revision,
+      },
+      state.provider,
+      Boolean(input.code && !input.error),
+    );
     if (claim.status === "replayed") return { redirectTo: stored.returnUrl, exactReturn: true };
     if (!personalOwnerStateAccepted(state))
       throw new HTTPException(403, { message: PERSONAL_CONNECTION_PRINCIPAL_MESSAGE });
@@ -455,46 +477,51 @@ async function completeSocialConnect(
         ...(token.expiresAt ? { expiresAt: token.expiresAt } : {}),
         ...(token.scope ? { scope: token.scope } : {}),
       };
-      await finishConnectOperation(deps.db, state, {
-        ...operation,
-        commit: async (tx, current) => {
-          const connection = await upsertSocialOAuthConnection(tx, {
-            accountId: state.accountId,
-            workspaceId: state.workspaceId,
-            ...(current.account
-              ? {
-                  expectedConnection: {
-                    id: current.account.id.slice("social:".length),
-                    version: current.account.version!,
-                  },
-                }
-              : {}),
-            subjectId: state.ownership === "personal" ? state.subjectId : null,
-            provider: provider.id,
-            accountHandle: identity.handle,
-            accountName: identity.name ?? null,
-            externalAccountId: identity.externalAccountId,
-            scopes: token.scope ? token.scope.split(/[\s,]+/).filter(Boolean) : state.scopes,
-            credentialEncrypted: encryptEnvironmentValue(key, JSON.stringify(bundle)),
-            tokenMetadata: publicTokenMetadata(bundle),
-          });
-          return {
-            ...current,
-            revision: current.revision + 1,
-            state: "complete",
-            credentialsCommitted: true,
-            nextAction: { type: "none" },
-            account: {
-              id: `social:${connection.id}`,
-              providerId: provider.id,
-              version: connection.version!,
-              label: identity.handle,
-              ownership: state.ownership,
-              status: "connected",
-            },
-          };
+      await finishOAuthAcquisition(
+        deps.db,
+        state,
+        {
+          ...operation,
+          commit: async (tx, current) => {
+            const connection = await upsertSocialOAuthConnection(tx, {
+              accountId: state.accountId,
+              workspaceId: state.workspaceId,
+              ...(current.account
+                ? {
+                    expectedConnection: {
+                      id: current.account.id.slice("social:".length),
+                      version: current.account.version!,
+                    },
+                  }
+                : {}),
+              subjectId: state.ownership === "personal" ? state.subjectId : null,
+              provider: provider.id,
+              accountHandle: identity.handle,
+              accountName: identity.name ?? null,
+              externalAccountId: identity.externalAccountId,
+              scopes: token.scope ? token.scope.split(/[\s,]+/).filter(Boolean) : state.scopes,
+              credentialEncrypted: encryptEnvironmentValue(key, JSON.stringify(bundle)),
+              tokenMetadata: publicTokenMetadata(bundle),
+            });
+            return {
+              ...current,
+              revision: current.revision + 1,
+              state: "complete",
+              credentialsCommitted: true,
+              nextAction: { type: "none" },
+              account: {
+                id: `social:${connection.id}`,
+                providerId: provider.id,
+                version: connection.version!,
+                label: identity.handle,
+                ownership: state.ownership,
+                status: "connected",
+              },
+            };
+          },
         },
-      });
+        state.provider,
+      );
     }
   } catch (error) {
     // An uncertain exchange stays occupied: do not replay a consumed OAuth code.

package/src/mcp/capability-account-readiness.ts

@@ -0,0 +1,17 @@
+import type { McpConnectionAccountBinding } from "@opengeni/contracts";
+
+/** Canonical readiness comes only from routes present in this exact attempt,
+ * joined to this turn's accepted bindings. It never grants account access. */
+export function capabilityAccountReadiness(
+  availableRoutes: Iterable<string>,
+  bindings: readonly McpConnectionAccountBinding[] | null,
+) {
+  const available = new Set(availableRoutes);
+  const actualRoutes = new Set(available);
+  const accepted = new Set<string>();
+  for (const binding of bindings ?? []) {
+    accepted.add(binding.canonicalServerId);
+    if (actualRoutes.has(binding.serverId)) available.add(binding.canonicalServerId);
+  }
+  return { available, accepted };
+}

package/src/mcp/editable-artifacts.ts

@@ -38,6 +38,7 @@ const ArtifactCommand = z
 const ArtifactMetadata = z
   .object({
     id: ArtifactId,
+    artifactReference: z.string(),
     modality: Modality,
     title: z.string(),
     lifecycle: z.enum(["active", "archived"]),
@@ -203,13 +204,17 @@ export function registerEditableArtifactAgentTools(
     {
       title: "Inspect editable artifact",
       description:
-        "Query the artifact's current canonical head through the same native kernel used by the browser. Use bounded modality queries; results are current, not a sandbox-file snapshot.",
+        "Query the artifact's current canonical head through the same native kernel used by the browser. Use bounded modality queries; results are current, not a sandbox-file snapshot. Native document queries return a server-issued inspectionReceiptId; use a post-edit body inspection receipt for declared report completion. If the document changes during inspection, retry against its current head.",
       inputSchema: {
         artifactId: ArtifactId,
         modality: Modality,
         request: EditableArtifactQueryRequestSchema,
       },
-      outputSchema: { artifact: ArtifactMetadata, projection: z.unknown() },
+      outputSchema: {
+        artifact: ArtifactMetadata,
+        projection: z.unknown(),
+        inspectionReceiptId: z.string().uuid().optional(),
+      },
       annotations: readOnlyAnnotations("Inspect editable artifact"),
     },
     async ({ artifactId, modality, request }, extra) =>

package/src/mcp/first-party-tool-permissions.ts

@@ -21,6 +21,7 @@ export const FIRST_PARTY_TOOL_AUTHORIZATION = {
   goal_pause: { sessionRequired: true, allOf: ["goals:manage"] },
   goal_resume: { sessionRequired: true, allOf: ["goals:manage"] },
   knowledge_search: { sessionRequired: true, allOf: ["documents:search"] },
+  knowledge_prepare_save: { sessionRequired: true, allOf: ["documents:search"] },
   knowledge_get: { sessionRequired: true, allOf: ["documents:search"] },
   knowledge_browse: { sessionRequired: true, allOf: ["documents:search"] },
   knowledge_retain_file: { sessionRequired: true, allOf: ["documents:search", "files:read"] },