@opengeni/api-router 2.11.3 → 2.12.3-canary.0

package/src/integrations/social-oauth.ts

@@ -15,6 +15,9 @@ import {
   loadSocialConnectionCredential,
   updateSocialConnectionCredential,
   upsertSocialOAuthConnection,
+  claimConnectOperation,
+  finishConnectOperation,
+  getConnectAttempt,
   type Database,
 } from "@opengeni/db";
 import { createSignedState, readSignedState } from "@opengeni/github";
@@ -29,6 +32,7 @@ import {
   PERSONAL_OWNER_VERIFIED_STATE_CLAIM,
 } from "../connection-ownership";
 import { ApiHttpError } from "../http/api-error";
+import { requireConnectOwnerAuthority } from "./connect-authority";
 import {
   integrationBaseUrl,
   oauthStateTtlMs,
@@ -135,6 +139,7 @@ function socialProviderFetch(
 }
 
 export type SocialOAuthStartContext = {
+  connectAttemptId?: string;
   accountId: string;
   workspaceId: string;
   subjectId: string;
@@ -148,6 +153,7 @@ export type SocialOAuthStartContext = {
 };
 
 type SocialOAuthStatePayload = {
+  connectAttemptId?: string;
   kind: "social_oauth";
   accountId: string;
   workspaceId: string;
@@ -201,6 +207,7 @@ export async function startSocialOAuth(
   const key = requireEnvironmentEncryption(settings);
   const state = createSignedState(requireIntegrationsStateSecret(settings), {
     kind: "social_oauth",
+    ...(context.connectAttemptId ? { connectAttemptId: context.connectAttemptId } : {}),
     accountId: context.accountId,
     workspaceId: context.workspaceId,
     subjectId: context.subjectId,
@@ -244,7 +251,7 @@ export async function completeSocialOAuthCallback(
     error?: string | undefined;
     requestUrl: string;
   },
-): Promise<{ redirectTo: string }> {
+): Promise<{ redirectTo: string; exactReturn?: boolean }> {
   const { db, settings, observability } = deps;
   let state: SocialOAuthStatePayload | null = null;
   try {
@@ -255,6 +262,7 @@ export async function completeSocialOAuthCallback(
       redirectTo: callbackReturnPath("/integrations", "error", { reason: "state_invalid" }),
     };
   }
+  if (state.connectAttemptId) return completeSocialConnect(deps, state, input);
   // Provider denial / missing code: report before burning the single-use
   // nonce so a user who cancelled at the provider can retry the same flow
   // within the state TTL.
@@ -365,6 +373,136 @@ export async function completeSocialOAuthCallback(
   }
 }
 
+/** Durable host setup keeps social credentials in their original domain. The
+ * stored origin, not the unauthenticated callback, supplies current authority. */
+async function completeSocialConnect(
+  deps: SocialOAuthDeps,
+  state: SocialOAuthStatePayload,
+  input: {
+    state?: string | undefined;
+    code?: string | undefined;
+    error?: string | undefined;
+    requestUrl: string;
+  },
+): Promise<{ redirectTo: string; exactReturn: true }> {
+  const stored = await getConnectAttempt(deps.db, state, state.connectAttemptId!);
+  if (stored.attempt.providerId !== state.provider || stored.attempt.ownership !== state.ownership)
+    throw new HTTPException(400, { message: "Social connection attempt mismatch" });
+  const authorize: import("@opengeni/db").ConnectOperationAuthorization = async (
+    tx,
+    _attempt,
+    origin,
+  ) => {
+    await requireConnectOwnerAuthority(
+      tx,
+      { ...state, ...(origin ? { externalContinuation: origin } : {}) },
+      state.ownership === "workspace" ? "workspace:admin" : "workspace:read",
+      origin,
+    );
+  };
+  const operation = {
+    attemptId: state.connectAttemptId!,
+    operationId: `social:${state.nonce}`,
+    inputDigest: createHash("sha256").update(input.state!).digest("hex"),
+    authorize,
+  };
+  try {
+    const claim = await claimConnectOperation(deps.db, state, {
+      ...operation,
+      expectedRevision: stored.attempt.revision,
+    });
+    if (claim.status === "replayed") return { redirectTo: stored.returnUrl, exactReturn: true };
+    if (!personalOwnerStateAccepted(state))
+      throw new HTTPException(403, { message: PERSONAL_CONNECTION_PRINCIPAL_MESSAGE });
+    if (input.error || !input.code) {
+      await finishConnectOperation(deps.db, state, {
+        ...operation,
+        commit: async (_tx, current) => ({
+          ...current,
+          revision: current.revision + 1,
+          state: input.error === "access_denied" ? "cancelled" : "failed",
+          nextAction: { type: "none" },
+          error: {
+            code: "authorization_not_completed",
+            message: "Authorization was not completed. Start a new attempt.",
+            retryable: false,
+          },
+        }),
+      });
+    } else {
+      const provider = SOCIAL_OAUTH_PROVIDERS[state.provider];
+      const key = requireEnvironmentEncryption(deps.settings);
+      const verifier = state.encryptedPkceVerifier
+        ? decryptEnvironmentValue(key, state.encryptedPkceVerifier)
+        : null;
+      const token = await socialTokenRequest(
+        deps,
+        provider,
+        socialOAuthClientFor(deps.settings, provider.id),
+        {
+          grant_type: "authorization_code",
+          code: input.code,
+          redirect_uri: socialOAuthRedirectUri(deps.settings, input.requestUrl),
+          ...(verifier ? { code_verifier: verifier } : {}),
+        },
+      );
+      const identity = await fetchSocialIdentity(deps, provider.id, token.accessToken);
+      const bundle: SocialCredentialBundle = {
+        provider: provider.id,
+        accessToken: token.accessToken,
+        tokenType: token.tokenType,
+        ...(token.refreshToken ? { refreshToken: token.refreshToken } : {}),
+        ...(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",
+            },
+          };
+        },
+      });
+    }
+  } catch (error) {
+    // An uncertain exchange stays occupied: do not replay a consumed OAuth code.
+    logSocialOAuthFailure(deps.observability, "connect_callback", state, error);
+  }
+  return { redirectTo: stored.returnUrl, exactReturn: true };
+}
+
 /**
  * Resolves a usable access token for a social connection, refreshing (and
  * persisting the rotated bundle) when the stored token is near expiry. Marks
@@ -706,6 +844,9 @@ function readSocialOAuthState(
   }
   return {
     kind: "social_oauth",
+    ...(typeof payload.connectAttemptId === "string"
+      ? { connectAttemptId: payload.connectAttemptId }
+      : {}),
     accountId: requiredStateString(payload.accountId, "accountId"),
     workspaceId: requiredStateString(payload.workspaceId, "workspaceId"),
     subjectId: requiredStateString(payload.subjectId, "subjectId"),

package/src/mcp/documents.ts

@@ -297,7 +297,7 @@ export function buildDocumentsMcpServer(
   if (memoryScope?.mode === "off") return server;
   const memoryReadScope: MemoryAgentScope = memoryScope ?? {
     mode: "workspace",
-    endUserSubjectId: null,
+    userSubjectId: null,
     rootSessionId: null,
   };
 

package/src/mcp/server.ts

@@ -15,6 +15,8 @@ import {
 } from "../site-uploads";
 import {
   CreateScheduledTaskRequest,
+  CreateSessionRequest,
+  GoalSpec,
   boundSessionMcpText as capSessionDiscoveryText,
   compactSessionMcpListRow,
   sessionMcpIncludesRelatedWork,
@@ -376,6 +378,45 @@ function orchestrationFailureCode(tool: OrchestrationToolName, error: HTTPExcept
   return `${tool}_${suffix}`.slice(0, ORCHESTRATION_FAILURE_CODE_MAX_LENGTH);
 }
 
+function sessionCreateValidationFailureResult(error: z4.ZodError) {
+  // Only call with issues from the raw request preflight, never downstream errors.
+  // Paths may contain caller-controlled record keys, and custom issue messages
+  // may contain values. Only publish canonical field names and fixed type labels.
+  const details = error.issues.slice(0, 5).map((issue) => {
+    const [field, goalField] = issue.path;
+    let path =
+      typeof field === "string" && Object.hasOwn(CreateSessionRequest.out.shape, field)
+        ? field
+        : "request";
+    if (
+      field === "goal" &&
+      typeof goalField === "string" &&
+      Object.hasOwn(GoalSpec.shape, goalField)
+    ) {
+      path += `.${goalField}`;
+    }
+    const expected =
+      issue.code === "invalid_type" &&
+      ["string", "number", "boolean", "object", "array", "int"].includes(issue.expected)
+        ? `expected ${issue.expected === "int" ? "integer" : issue.expected}`
+        : "failed schema validation";
+    return `${path} ${expected}`;
+  });
+  const envelope = {
+    error: {
+      code: "session_create_invalid_request",
+      message: boundedOrchestrationFailureMessage(
+        `Invalid session create request: ${details.join("; ") || "request failed schema validation"}${error.issues.length > 5 ? "; additional fields failed validation" : ""}.`,
+      ),
+    },
+  };
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(envelope, null, 2) }],
+    structuredContent: envelope,
+    isError: true as const,
+  };
+}
+
 function orchestrationFailureEnvelope(tool: OrchestrationToolName, error: unknown) {
   if (error instanceof SessionSpawnDeniedError) {
     const denial = sessionSpawnDenialEnvelope(error);
@@ -3613,7 +3654,7 @@ function registerMemoryTools(
   // session's narrowest layer. A null scope is the pre-0426 workspace path.
   const agentScope: MemoryAgentScope = sessionMemory ?? {
     mode: "workspace",
-    endUserSubjectId: null,
+    userSubjectId: null,
     rootSessionId: null,
   };
   const writeScope = memoryWriteScopeForAgentScope(agentScope);
@@ -5102,7 +5143,7 @@ function registerWorkspaceOrchestrationTools(
             "Concise semantic title for the child session. Omit only when the delegated goal or initial message already provides a suitable title; OpenGeni derives a sensitive-safe bounded fallback from that text.",
           ),
         instructions: z4.string().min(1).max(SESSION_INSTRUCTIONS_MAX_CHARACTERS).optional(),
-        goal: z4.unknown().optional(),
+        goal: GoalSpec.optional(),
         resources: z4
           .array(z4.unknown())
           .optional()
@@ -5157,12 +5198,12 @@ function registerWorkspaceOrchestrationTools(
           ),
         // The child's agent-access scope and end-user label are never model
         // choices: it inherits this session's exactly. Only the Memory
-        // selector may be narrowed here (workspace > user > session > off).
+        // selector may be narrowed here (workspace > user > off).
         memoryScope: z4
-          .enum(["workspace", "user", "session", "off"])
+          .enum(["workspace", "user", "off"])
           .optional()
           .describe(
-            "Optional Memory selector for the child. Omit to inherit this session's selector. An explicit value may only narrow it (workspace > user > session > off); off gives the child no Memory tools.",
+            "Optional Memory selector for the child. Omit to inherit this session's selector. An explicit value may only narrow it (workspace > user > off); off gives the child no Memory tools. Use task notes for task-local findings.",
           ),
         // Omission is the ordinary safe sharing path. Literal "shared" remains
         // available to advanced REST/SDK callers but is intentionally absent
@@ -5211,22 +5252,28 @@ function registerWorkspaceOrchestrationTools(
             await authorizeFirstPartySession(deps, grant, callerSessionId, "session.child.create");
           }
           const { machineTarget, title, projectId, ...request } = args;
+          const rawRequest = {
+            ...request,
+            ...(projectId !== undefined ? { channelId: projectId } : {}),
+            ...(machineTarget
+              ? {
+                  targetSandboxId: machineTarget.targetSandboxId,
+                  ...(machineTarget.workingDir !== undefined
+                    ? { workingDir: machineTarget.workingDir }
+                    : {}),
+                }
+              : {}),
+          };
+          // Keep authorization above validation and let core parse the original
+          // request. Only this preflight's failures are attributable to input;
+          // arbitrary downstream schema failures retain the private fallback.
+          const validation = CreateSessionRequest.safeParse(rawRequest);
+          if (!validation.success) return sessionCreateValidationFailureResult(validation.error);
           const result = await createSessionForRequestWithOutcome(
             deps,
             grant,
             grant.workspaceId,
-            {
-              ...request,
-              ...(projectId !== undefined ? { channelId: projectId } : {}),
-              ...(machineTarget
-                ? {
-                    targetSandboxId: machineTarget.targetSandboxId,
-                    ...(machineTarget.workingDir !== undefined
-                      ? { workingDir: machineTarget.workingDir }
-                      : {}),
-                  }
-                : {}),
-            },
+            rawRequest,
             undefined,
             title === undefined ? {} : { automaticTitleCandidate: title },
           );

package/src/routes/api-integrations.ts

@@ -15,6 +15,7 @@ import {
   PreviewApiIntegrationRequest,
   UninstallApiIntegrationRequest,
   UninstallApiIntegrationResult,
+  type AccessGrant,
 } from "@opengeni/contracts";
 import { requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
 import {
@@ -37,6 +38,7 @@ import { HTTPException } from "hono/http-exception";
 import {
   resolveApiIntegrationPreview,
   type ApiIntegrationConnectionDescriptor,
+  type ResolvedApiIntegrationPreview,
 } from "../integrations/api-integrations";
 
 export type ApiIntegrationRouteOverrides = Readonly<{ fetchImpl?: FetchLike }>;
@@ -46,6 +48,72 @@ export function apiIntegrationRequiresConnection(authScheme: Record<string, unkn
   return typeof authKind === "string" && authKind !== "none";
 }
 
+/** Shared native/embedded install validation. The caller must still authorize
+ * capabilities:manage and commit under its own live-authority boundary. */
+export function validatedIntegrationInstallInput(
+  grant: AccessGrant,
+  workspaceId: string,
+  payload: InstallApiIntegrationRequest,
+  resolved: ResolvedApiIntegrationPreview,
+): Parameters<typeof installApiIntegration>[1] {
+  if (
+    resolved.preview.revisionId !== payload.expectedRevisionId ||
+    resolved.preview.contentSha256 !== payload.expectedContentSha256
+  ) {
+    throw new HTTPException(409, {
+      message:
+        "The Integration source changed after preview. Review the new tools and permissions before installing.",
+    });
+  }
+  if (resolved.preview.auth.kind !== "none" && !payload.connectionId)
+    throw new HTTPException(422, {
+      message: "Connect an account before installing this Integration.",
+    });
+  if (
+    payload.ownership &&
+    resolved.preview.connectionOwnership &&
+    payload.ownership !== resolved.preview.connectionOwnership
+  )
+    throw new HTTPException(422, {
+      message: "The selected Connection ownership does not match this install request.",
+    });
+  if (payload.ownership === "personal" && !resolved.preview.connectionOwnership)
+    throw new HTTPException(422, {
+      message: "Choose a Personal Connection before installing for yourself.",
+    });
+  return {
+    accountId: grant.accountId,
+    workspaceId,
+    subjectId: grant.subjectId,
+    capabilityId: resolved.preview.capabilityId,
+    pluginKey: resolved.preview.pluginKey,
+    serverId: resolved.preview.serverId,
+    name: resolved.preview.name,
+    description: resolved.preview.description,
+    category: "integrations",
+    tags: [resolved.preview.protocol, resolved.preview.provider ?? "custom"],
+    definitionId: resolved.preview.definitionId,
+    definitionProvenance: resolved.preview.definitionProvenance,
+    ...(resolved.provider ? { provider: resolved.provider } : {}),
+    providerDomain: resolved.preview.providerDomain,
+    protocol: resolved.preview.protocol,
+    baseUrl: resolved.preview.baseUrl,
+    sourceUrl: resolved.preview.sourceUrl,
+    authScheme: resolved.authScheme,
+    ...(payload.connectionId ? { connectionId: payload.connectionId } : {}),
+    ...(payload.instanceKey ? { instanceKey: payload.instanceKey } : {}),
+    ...(payload.displayName ? { displayName: payload.displayName } : {}),
+    ...(payload.expectedInstanceVersion !== undefined
+      ? { expectedInstanceVersion: payload.expectedInstanceVersion }
+      : {}),
+    requiredScopes: resolved.requiredScopes,
+    ownership: resolved.preview.connectionOwnership === "personal" ? "subject" : "workspace",
+    ...(payload.allowedTools ? { allowedTools: payload.allowedTools } : {}),
+    facetDefinitions: integrationFacetDefinitions(resolved.preview.definitionId),
+    revision: resolved.revision,
+  };
+}
+
 export function registerApiIntegrationRoutes(
   app: Hono,
   deps: ApiRouteDeps,
@@ -53,7 +121,9 @@ export function registerApiIntegrationRoutes(
 ): void {
   const transport = createPinnedIntegrationTransport({
     network: deps.settings,
-    ...(overrides.fetchImpl ? { fetchImpl: overrides.fetchImpl } : {}),
+    ...((overrides.fetchImpl ?? deps.apiIntegrationSourceFetch)
+      ? { fetchImpl: overrides.fetchImpl ?? deps.apiIntegrationSourceFetch! }
+      : {}),
   });
 
   app.get("/v1/workspaces/:workspaceId/integrations/definitions", async (c) => {
@@ -157,70 +227,10 @@ export function registerApiIntegrationRoutes(
       subjectId: grant.subjectId,
       payload,
     });
-    if (
-      resolved.preview.revisionId !== payload.expectedRevisionId ||
-      resolved.preview.contentSha256 !== payload.expectedContentSha256
-    ) {
-      throw new HTTPException(409, {
-        message:
-          "The Integration source changed after preview. Review the new tools and permissions before installing.",
-      });
-    }
-    if (resolved.preview.auth.kind !== "none" && !payload.connectionId) {
-      throw new HTTPException(422, {
-        message: "Connect an account before installing this Integration.",
-      });
-    }
-    if (
-      payload.ownership &&
-      resolved.preview.connectionOwnership &&
-      payload.ownership !== resolved.preview.connectionOwnership
-    ) {
-      throw new HTTPException(422, {
-        message: "The selected Connection ownership does not match this install request.",
-      });
-    }
-    if (payload.ownership === "personal" && !resolved.preview.connectionOwnership) {
-      throw new HTTPException(422, {
-        message: "Choose a Personal Connection before installing for yourself.",
-      });
-    }
+    const installation = validatedIntegrationInstallInput(grant, workspaceId, payload, resolved);
     try {
       return c.json(
-        InstalledApiIntegration.parse(
-          await installApiIntegration(deps.db, {
-            accountId: grant.accountId,
-            workspaceId,
-            subjectId: grant.subjectId,
-            capabilityId: resolved.preview.capabilityId,
-            pluginKey: resolved.preview.pluginKey,
-            serverId: resolved.preview.serverId,
-            name: resolved.preview.name,
-            description: resolved.preview.description,
-            category: "integrations",
-            tags: [resolved.preview.protocol, resolved.preview.provider ?? "custom"],
-            definitionId: resolved.preview.definitionId,
-            definitionProvenance: resolved.preview.definitionProvenance,
-            ...(resolved.provider ? { provider: resolved.provider } : {}),
-            providerDomain: resolved.preview.providerDomain,
-            protocol: resolved.preview.protocol,
-            baseUrl: resolved.preview.baseUrl,
-            sourceUrl: resolved.preview.sourceUrl,
-            authScheme: resolved.authScheme,
-            ...(payload.connectionId ? { connectionId: payload.connectionId } : {}),
-            ...(payload.instanceKey ? { instanceKey: payload.instanceKey } : {}),
-            ...(payload.displayName ? { displayName: payload.displayName } : {}),
-            ...(payload.expectedInstanceVersion !== undefined
-              ? { expectedInstanceVersion: payload.expectedInstanceVersion }
-              : {}),
-            requiredScopes: resolved.requiredScopes,
-            ownership:
-              resolved.preview.connectionOwnership === "personal" ? "subject" : "workspace",
-            ...(payload.allowedTools ? { allowedTools: payload.allowedTools } : {}),
-            facetDefinitions: integrationFacetDefinitions(resolved.preview.definitionId),
-            revision: resolved.revision,
-          }),
-        ),
+        InstalledApiIntegration.parse(await installApiIntegration(deps.db, installation)),
         payload.expectedInstanceVersion === undefined ? 201 : 200,
       );
     } catch (error) {
@@ -295,7 +305,7 @@ export function registerApiIntegrationRoutes(
   );
 }
 
-async function resolveForRoute(input: {
+export async function resolveForRoute(input: {
   deps: ApiRouteDeps;
   transport: ReturnType<typeof createPinnedIntegrationTransport>;
   workspaceId: string;