@opengeni/api-router 3.0.1 → 3.0.2-canary.38894290271001

package/src/integrations/slack-task-file-upload.ts

@@ -0,0 +1,323 @@
+import { createHash } from "node:crypto";
+import {
+  hasOpenGeniSlackFileUploadScope,
+  OPENGENI_SLACK_BOT_CREDENTIAL_LABEL,
+  OPENGENI_SLACK_BOT_CREDENTIAL_ROLE,
+  type AccessGrant,
+} from "@opengeni/contracts";
+import {
+  fileOwnerContextForAgent,
+  hasPermission,
+  requireOpenGeniSlackBotConnection,
+  requirePermission,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import {
+  checkpointSlackFileUpload,
+  claimSlackFileUpload,
+  getSlackBotUserLink,
+  getSlackInteractionForSession,
+  recordAuditEvent,
+  releaseSlackFileUploadClaim,
+  renewSlackFileUploadClaim,
+  requireFileForSubject,
+  resolveSlackInstallationRoute,
+  resolveSlackTargetAuthority,
+  withSessionRlsActorContext,
+  type SlackInteraction,
+} from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+import { createOpenGeniSlackBotInteractionClient } from "./slack-bot";
+import { runSlackFileUpload, SlackFileUploadClaimLostError } from "./slack-file-upload-flow";
+
+export const SLACK_TASK_FILE_UPLOAD_MAX_BYTES = 25 * 1024 * 1024;
+const CLAIM_LEASE_MS = 60_000;
+
+/** The source and destination are canonical authorities, never a URL or channel supplied by the model. */
+export async function uploadSlackTaskFile(
+  deps: ApiRouteDeps,
+  input: {
+    grant: AccessGrant;
+    sessionId: string;
+    fileId: string;
+    operationId: string;
+    authorize: () => Promise<void>;
+  },
+) {
+  await input.authorize();
+  const { grant } = input;
+  requirePermission(grant, "connections:read");
+  const actor = await fileOwnerContextForAgent(deps, grant, "files:read");
+  const scope = { accountId: grant.accountId, workspaceId: grant.workspaceId };
+  const resolveTarget = async () => {
+    const interaction = await getSlackInteractionForSession(deps.db, {
+      ...scope,
+      sessionId: input.sessionId,
+    });
+    if (
+      !interaction?.initiatingSlackUserId ||
+      !interaction.slackThreadTs ||
+      !/^\d{1,20}\.\d{1,12}$/.test(interaction.slackThreadTs)
+    ) {
+      throw new HTTPException(422, {
+        message: "File delivery requires this session's existing Slack task thread",
+      });
+    }
+    if (
+      interaction.visibility === "private" &&
+      actor.initiatingHumanSubjectId !== interaction.owningSubjectId
+    ) {
+      throw new HTTPException(403, {
+        message: "Private Slack file delivery requires the task owner's current attempt",
+      });
+    }
+    assertSlackTaskUploadTarget(interaction);
+    const home = await resolveSlackInstallationRoute(deps.db, interaction.slackTeamId);
+    if (
+      !home ||
+      home.accountId !== grant.accountId ||
+      home.connectionId !== interaction.connectionId
+    ) {
+      throw new HTTPException(403, { message: "Slack task installation authority changed" });
+    }
+    const link = await getSlackBotUserLink(
+      deps.db,
+      home.workspaceId,
+      interaction.connectionId,
+      interaction.initiatingSlackUserId,
+    );
+    if (!link || link.subjectId !== interaction.owningSubjectId) {
+      throw new HTTPException(403, { message: "Slack task requester is no longer linked" });
+    }
+    const requester = await resolveSlackTargetAuthority(deps.db, {
+      subjectId: link.subjectId,
+      targetAccountId: grant.accountId,
+      targetWorkspaceId: grant.workspaceId,
+    });
+    if (!requester || !slackTaskRequesterCanReceiveFile(requester.permissions)) {
+      throw new HTTPException(403, {
+        message: "Slack task requester no longer has file delivery access",
+      });
+    }
+    return { interaction, home };
+  };
+
+  return withSessionRlsActorContext(actor, async () => {
+    const target = await resolveTarget();
+    const file = await requireFileForSubject(deps.db, {
+      ...scope,
+      subjectId: grant.subjectId,
+      fileId: input.fileId,
+    });
+    if (file.workspaceId !== grant.workspaceId) {
+      throw new HTTPException(422, {
+        message: "Select a retained file from this Slack task's workspace",
+      });
+    }
+    assertSlackTaskUploadFile(file, target.interaction.visibility);
+    const connection = await requireOpenGeniSlackBotConnection(
+      deps.db,
+      target.home.workspaceId,
+      target.interaction.connectionId,
+    );
+    if (!hasOpenGeniSlackFileUploadScope(connection.grantedScopes)) {
+      throw new HTTPException(422, {
+        message:
+          "A Slack administrator must apply the Opengeni bot manifest and reinstall the bot to grant files:write. A personal Slack connection is not needed.",
+      });
+    }
+    if (!deps.objectStorage)
+      throw new HTTPException(503, { message: "Retained file storage is unavailable" });
+    let stored;
+    try {
+      stored = await deps.objectStorage.getObjectBytes(file.objectKey);
+    } catch {
+      throw new HTTPException(503, { message: "Retained file content is unavailable" });
+    }
+    if (
+      !stored ||
+      stored.bytes.byteLength !== file.sizeBytes ||
+      createHash("sha256").update(stored.bytes).digest("hex") !== file.sha256
+    ) {
+      throw new HTTPException(409, {
+        message: "Retained file content does not match its immutable identity",
+      });
+    }
+    const filename = file.safeFilename.slice(0, 200);
+    if (!filename || /[\r\n\0]/.test(filename))
+      throw new HTTPException(422, { message: "Invalid retained filename" });
+    const binding = {
+      ...scope,
+      sessionId: input.sessionId,
+      interactionId: target.interaction.id,
+      connectionId: target.interaction.connectionId,
+      fileId: input.fileId,
+      subjectId: actor.initiatingHumanSubjectId ?? grant.subjectId,
+      operationId: input.operationId,
+      requestDigest: createHash("sha256")
+        .update(
+          JSON.stringify({
+            fileId: file.id,
+            sha256: file.sha256,
+            sizeBytes: file.sizeBytes,
+            contentType: file.contentType,
+            filename,
+            channelId: target.interaction.slackChannelId,
+            threadTimestamp: target.interaction.slackThreadTs,
+            connectionId: target.interaction.connectionId,
+            slackTeamId: target.interaction.slackTeamId,
+          }),
+        )
+        .digest("hex"),
+    };
+    const claimHolderId = crypto.randomUUID();
+    const claim = await claimSlackFileUpload(deps.db, {
+      ...binding,
+      claimHolderId,
+      leaseMs: CLAIM_LEASE_MS,
+    });
+    if (claim.status === "conflict")
+      throw new HTTPException(409, {
+        message: "operationId is already bound to a different Slack file delivery",
+      });
+    if (claim.status === "busy")
+      throw new HTTPException(409, {
+        message: "Slack file delivery is already in progress; retry with the same operationId",
+      });
+    const claimScope = {
+      ...scope,
+      sessionId: input.sessionId,
+      operationId: input.operationId,
+      claimHolderId,
+    };
+    const authorizeProviderRequest = async () => {
+      await input.authorize();
+      await fileOwnerContextForAgent(deps, grant, "files:read");
+      const currentTarget = await resolveTarget();
+      if (
+        currentTarget.interaction.id !== target.interaction.id ||
+        currentTarget.interaction.connectionId !== target.interaction.connectionId ||
+        currentTarget.interaction.slackChannelId !== target.interaction.slackChannelId ||
+        currentTarget.interaction.slackThreadTs !== target.interaction.slackThreadTs ||
+        currentTarget.interaction.visibility !== target.interaction.visibility ||
+        currentTarget.home.workspaceId !== target.home.workspaceId
+      )
+        throw new HTTPException(403, { message: "Slack file delivery target changed" });
+      const currentFile = await requireFileForSubject(deps.db, {
+        ...scope,
+        subjectId: grant.subjectId,
+        fileId: file.id,
+      });
+      assertSlackTaskUploadFile(currentFile, currentTarget.interaction.visibility);
+      if (
+        currentFile.sha256 !== file.sha256 ||
+        currentFile.sizeBytes !== file.sizeBytes ||
+        currentFile.objectKey !== file.objectKey
+      ) {
+        throw new HTTPException(409, { message: "Slack file delivery source changed" });
+      }
+      if (!(await renewSlackFileUploadClaim(deps.db, { ...claimScope, leaseMs: CLAIM_LEASE_MS })))
+        throw new SlackFileUploadClaimLostError();
+    };
+    try {
+      const client = await createOpenGeniSlackBotInteractionClient(
+        { ...deps, authorizeProviderRequest },
+        {
+          accountId: target.home.accountId,
+          workspaceId: target.home.workspaceId,
+          connectionId: target.interaction.connectionId,
+          subjectId: grant.subjectId,
+          sessionId: input.sessionId,
+        },
+      );
+      const result = await runSlackFileUpload({
+        state: claim.operation,
+        provider: client,
+        checkpoint: (update) => checkpointSlackFileUpload(deps.db, { ...claimScope, ...update }),
+        channelId: target.interaction.slackChannelId,
+        threadTimestamp: target.interaction.slackThreadTs!,
+        ...(target.interaction.visibility === "private"
+          ? { privateRecipientSlackUserId: target.interaction.initiatingSlackUserId! }
+          : {}),
+        filename,
+        bytes: stored.bytes,
+      });
+      await recordAuditEvent(deps.db, {
+        ...scope,
+        subjectId: grant.subjectId,
+        action: "slack.file.upload",
+        targetType: "workspace_file",
+        targetId: file.id,
+        metadata: {
+          operationId: input.operationId,
+          sessionId: input.sessionId,
+          interactionId: target.interaction.id,
+          slackFileId: result.slackFileId,
+          replayed: result.replayed,
+        },
+      });
+      return {
+        status: "uploaded" as const,
+        fileId: file.id,
+        ...result,
+        channelId: target.interaction.slackChannelId,
+        threadTimestamp: target.interaction.slackThreadTs,
+        receipt: {
+          credentialRole: OPENGENI_SLACK_BOT_CREDENTIAL_ROLE,
+          credentialLabel: OPENGENI_SLACK_BOT_CREDENTIAL_LABEL,
+          connectionId: target.interaction.connectionId,
+          slackTeamId: target.interaction.slackTeamId,
+          operation: "file.upload",
+          operationId: input.operationId,
+        },
+      };
+    } finally {
+      if (claim.status === "claimed") await releaseSlackFileUploadClaim(deps.db, claimScope);
+    }
+  });
+}
+
+export function slackTaskRequesterCanReceiveFile(permissions: AccessGrant["permissions"]): boolean {
+  return hasPermission(permissions, "files:read") && hasPermission(permissions, "sessions:read");
+}
+
+/** Private shortcuts bind a runnable session before its bot-DM route commits. */
+export function assertSlackTaskUploadTarget(
+  interaction: Pick<
+    SlackInteraction,
+    "visibility" | "slackChannelId" | "slackThreadTs" | "routeKey" | "ackSlackMessageTs"
+  >,
+): void {
+  if (
+    interaction.visibility === "private" &&
+    (!interaction.slackChannelId.startsWith("D") ||
+      interaction.routeKey !== `${interaction.slackChannelId}:${interaction.slackThreadTs}` ||
+      (interaction.ackSlackMessageTs !== null &&
+        interaction.ackSlackMessageTs !== interaction.slackThreadTs))
+  ) {
+    throw new HTTPException(409, {
+      message: "Private Slack file delivery must wait for this task's committed bot-DM thread",
+    });
+  }
+}
+
+export function assertSlackTaskUploadFile(
+  file: { status: string; scope?: string | undefined; sizeBytes: number; sha256: string | null },
+  visibility: string,
+): void {
+  if (file.status !== "ready" || !file.sha256 || !/^[a-f0-9]{64}$/.test(file.sha256)) {
+    throw new HTTPException(422, {
+      message: "Publish a ready, immutable file before uploading it to Slack",
+    });
+  }
+  if (file.scope === "personal" && visibility !== "private") {
+    throw new HTTPException(403, {
+      message: "Personal files cannot be uploaded to a shared Slack task thread",
+    });
+  }
+  if (file.sizeBytes < 1 || file.sizeBytes > SLACK_TASK_FILE_UPLOAD_MAX_BYTES) {
+    throw new HTTPException(413, {
+      message: "Slack task file delivery supports nonempty files up to 25 MiB",
+    });
+  }
+}

package/src/integrations/slack-tool-review.ts

@@ -0,0 +1,65 @@
+import type { ToolActionReview } from "@opengeni/contracts";
+import type { SlackMessageBlock } from "./slack-bot";
+
+/** Shared review facts, projected only into a proven private bot conversation. */
+export function slackToolReviewCanDecide(review: ToolActionReview): boolean {
+  // Delivery retries belong to the original review event. Its content must not
+  // change when a later decision changes status, revision or availableActions.
+  return (
+    review.detailsAvailable &&
+    reviewLines(review).every((line) => line.length <= 2800) &&
+    JSON.stringify({
+      title: review.title,
+      account: review.accountLabel,
+      consequence: review.consequence,
+      effects: review.effects,
+      samples: review.samples,
+      fields: review.fields,
+      moreFields: review.moreFields,
+      reason: review.reason,
+    }).length <= 6000
+  );
+}
+
+export function slackToolReviewBlocks(
+  review: ToolActionReview,
+  privateAudience: boolean,
+): SlackMessageBlock[] {
+  if (!privateAudience || !slackToolReviewCanDecide(review))
+    return [
+      {
+        type: "section",
+        text: {
+          type: "plain_text",
+          text: "An action needs review. Open the task to review its private details.",
+        },
+      },
+    ];
+  const lines = reviewLines(review);
+  const blocks: SlackMessageBlock[] = [];
+  let text = "";
+  for (const line of lines) {
+    if (text && text.length + line.length + 1 > 2800) {
+      blocks.push({ type: "section", text: { type: "plain_text", text } });
+      text = "";
+    }
+    text += `${text ? "\n" : ""}${line}`;
+  }
+  if (text) blocks.push({ type: "section", text: { type: "plain_text", text } });
+  return blocks;
+}
+
+function reviewLines(review: ToolActionReview): string[] {
+  return [
+    review.title,
+    review.accountLabel,
+    review.consequence,
+    ...review.effects,
+    ...(review.samples ?? []).map((sample) =>
+      [sample.title, sample.subtitle].filter(Boolean).join(" — "),
+    ),
+    ...review.fields.map((field) => `${field.label}: ${field.preview}`),
+    review.moreFields ? `${review.moreFields} more fields in full details.` : null,
+    review.reason,
+  ].filter((line): line is string => Boolean(line));
+}

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,
@@ -35,8 +36,10 @@ import { ApiHttpError } from "../http/api-error";
 import { requireConnectOwnerAuthority } from "./connect-authority";
 import {
   integrationBaseUrl,
+  oauthStateFailureReturn,
   oauthStateTtlMs,
   requireIntegrationsStateSecret,
+  workspaceIntegrationsPath,
 } from "./oauth-client";
 
 // Reddit requires a descriptive, stable User-Agent on every request (token
@@ -196,9 +199,12 @@ 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");
+  const returnPath = safeReturnPath(
+    context.payload.returnPath ?? workspaceIntegrationsPath(context.workspaceId),
+  );
   const scopes = uniqueScopes(context.payload.scopes) ?? provider.defaultScopes;
   const verifier = provider.pkce ? randomBytes(32).toString("base64url") : null;
   // Require the encryption key for every provider (not just PKCE ones) so a
@@ -258,8 +264,9 @@ export async function completeSocialOAuthCallback(
     state = readSocialOAuthState(input.state, settings);
   } catch (error) {
     logSocialOAuthFailure(observability, "state_verify", state, error);
+    const failure = oauthStateFailureReturn(settings, input.state);
     return {
-      redirectTo: callbackReturnPath("/integrations", "error", { reason: "state_invalid" }),
+      redirectTo: callbackReturnPath(failure.returnPath, "error", { reason: failure.reason }),
     };
   }
   if (state.connectAttemptId) return completeSocialConnect(deps, state, input);
@@ -323,6 +330,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 +352,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 +428,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 +482,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.