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

package/src/integrations/slack-bot.ts

@@ -5,8 +5,10 @@ import {
   OPENGENI_SLACK_BOT_CREDENTIAL_ROLE,
   OPENGENI_SLACK_BOT_REQUIRED_SCOPES,
   evaluateOpenGeniSlackBotScopes,
+  hasOpenGeniSlackBotSearchScopes,
   type AccessGrant,
   type ConnectionMetadata,
+  type OpenGeniSlackBotDisplayName,
   type OpenGeniSlackBotConnectionMetadata,
 } from "@opengeni/contracts";
 import {
@@ -64,6 +66,12 @@ const MAX_REACTION_CONTEXT_CHECKPOINT_FILE_LABEL_CHARS = 1_500;
 const MAX_REACTION_CONTEXT_CHECKPOINT_FILES = 16;
 const SLACK_REACTION_CONTEXT_CHECKPOINT_VERSION = 1;
 const MAX_USER_PAGE = 200;
+/** Slack caps `assistant.search.context` at 20 results per request. */
+const MAX_SEARCH_PAGE = 20;
+/** Bounded projection cap for one search result's content excerpt. */
+const MAX_SEARCH_CONTENT_CHARS = 2_000;
+/** Matches the MCP input schema's cap; Slack signals its own via query_too_long. */
+const MAX_SEARCH_QUERY_CHARS = 500;
 const MAX_FILE_PAGE = 200;
 const MAX_FILE_CURSOR_LENGTH = 1_024;
 const SLACK_FILE_CURSOR_VERSION = "files-v1";
@@ -106,6 +114,11 @@ export type DownloadedSlackReactionImage = Readonly<{
   bytes: Uint8Array;
 }>;
 
+export type ExchangedOpenGeniSlackAuthorization = Readonly<{
+  accessToken: string;
+  appId: string;
+}>;
+
 export async function exchangeOpenGeniSlackAuthorizationCode(
   input: {
     code: string;
@@ -114,7 +127,7 @@ export async function exchangeOpenGeniSlackAuthorizationCode(
     redirectUri: string;
   },
   fetchImpl: FetchLike = fetch,
-): Promise<string> {
+): Promise<ExchangedOpenGeniSlackAuthorization> {
   const body = new URLSearchParams({
     code: input.code,
     client_id: input.clientId,
@@ -158,7 +171,13 @@ export async function exchangeOpenGeniSlackAuthorizationCode(
       message: "Slack installation did not return a bot token",
     });
   }
-  return accessToken;
+  const appId = slackString(record.app_id);
+  if (!appId) {
+    throw new HTTPException(502, {
+      message: "Slack installation did not return an app identity",
+    });
+  }
+  return { accessToken, appId };
 }
 
 export type SlackBotReceipt = {
@@ -188,16 +207,58 @@ export type SlackMessageBlock =
         style?: "primary" | "danger";
       }>;
     }
+  | {
+      type: "context";
+      block_id?: string;
+      elements: Array<{ type: "mrkdwn" | "plain_text"; text: string; emoji?: boolean }>;
+    }
+  | { type: "divider" };
+
+export type SlackHomeBlock =
+  | {
+      type: "header";
+      block_id?: string;
+      text: { type: "plain_text"; text: string; emoji?: boolean };
+    }
+  | {
+      type: "section";
+      block_id?: string;
+      text: { type: "mrkdwn" | "plain_text"; text: string; emoji?: boolean };
+      accessory?: {
+        type: "button";
+        action_id: string;
+        text: { type: "plain_text"; text: string; emoji?: boolean };
+        url: string;
+      };
+    }
+  | {
+      type: "context";
+      block_id?: string;
+      elements: Array<{ type: "mrkdwn" | "plain_text"; text: string; emoji?: boolean }>;
+    }
+  | {
+      type: "actions";
+      block_id: string;
+      elements: Array<{
+        type: "button";
+        action_id: string;
+        text: { type: "plain_text"; text: string; emoji?: boolean };
+        url: string;
+        style?: "primary" | "danger";
+      }>;
+    }
   | { type: "divider" };
 
 type SlackBotOperation =
   | "channels.list"
+  | "search.context"
   | "channel_history.read"
   | "thread_replies.read"
   | "users.list"
   | "files.list"
   | "file.info"
   | "file.content.read"
+  | "home.publish"
   | "message.post"
   | "message.update"
   | "message.delete";
@@ -210,6 +271,9 @@ type SlackBotContext = {
   scheduledTaskId?: string | null;
 };
 
+type SlackCallAuthority = Readonly<{ operation: SlackBotOperation }>;
+type SlackProviderAuthorization = () => Promise<boolean | void>;
+
 export type SlackReactionContextCheckpointBinding = {
   inboxId: string;
   accountId: string;
@@ -259,6 +323,35 @@ export class SlackBotProviderError extends Error {
   }
 }
 
+export async function authorizeSlackSharedImageRead(
+  channel: {
+    isArchived: boolean;
+    isShared: boolean;
+    isExternallyShared: boolean;
+    isOrgShared: boolean;
+    isPendingExternallyShared: boolean;
+    isMpim: boolean;
+  },
+  authorizeSharedRead: (() => Promise<void>) | undefined,
+): Promise<void> {
+  if (channel.isArchived) {
+    throw new SlackBotProviderError("is_archived");
+  }
+  if (
+    !channel.isShared &&
+    !channel.isExternallyShared &&
+    !channel.isOrgShared &&
+    !channel.isPendingExternallyShared &&
+    !channel.isMpim
+  ) {
+    throw new SlackBotProviderError("slack_connect_unsupported");
+  }
+  if (!authorizeSharedRead) {
+    throw new SlackBotProviderError("slack_connect_unsupported");
+  }
+  await authorizeSharedRead();
+}
+
 const SLACK_CREDENTIAL_REJECTION_CODES = new Set([
   "account_inactive",
   "invalid_auth",
@@ -285,12 +378,16 @@ export class SlackBotCredentialVerificationError extends HTTPException {
 
 /**
  * Validates a write-only xoxb credential before it can enter encrypted storage.
- * Slack does not expose the app's display_information name to this scope set;
- * users.info provides the authoritative installed bot display name, while the
- * documented manifest fixes the app name itself to the same exact value.
+ * The OAuth exchange's app_id is the immutable app authority. Slack bot profile
+ * names are mutable presentation data and may lag manifest/App Home changes, so
+ * they must not decide whether a credential belongs to this installation.
  */
 export async function verifyOpenGeniSlackBotCredential(
   token: string,
+  expected: Readonly<{
+    appId: string;
+    displayName: OpenGeniSlackBotDisplayName;
+  }>,
   fetchImpl: FetchLike = fetch,
   now: Date = new Date(),
 ): Promise<VerifiedOpenGeniSlackBot> {
@@ -314,11 +411,11 @@ export async function verifyOpenGeniSlackBotCredential(
     );
   }
   const profile = slackRecord(user.profile);
-  const displayName = slackString(profile?.display_name) || slackString(profile?.real_name);
-  if (displayName !== "OpenGeni") {
+  const installedAppId = slackString(profile?.api_app_id);
+  if (installedAppId !== expected.appId) {
     throw new SlackBotCredentialVerificationError(
       "identity_mismatch",
-      'Slack bot display name must be exactly "OpenGeni"',
+      "Slack credential does not belong to the authorized Slack app",
     );
   }
 
@@ -331,7 +428,7 @@ export async function verifyOpenGeniSlackBotCredential(
       slackTeamName,
       botUserId,
       botId,
-      botDisplayName: "OpenGeni",
+      botDisplayName: expected.displayName,
       verifiedAt: now.toISOString(),
     },
   };
@@ -427,6 +524,7 @@ export class OpenGeniSlackBotClient {
     private readonly metadata: OpenGeniSlackBotConnectionMetadata,
     private readonly context: SlackBotContext,
     private readonly fetchImpl: FetchLike = fetch,
+    private readonly authorizeProviderRequest?: SlackProviderAuthorization,
   ) {
     this.resolveCredential = buildConnectionTokenResolver(db, settings);
   }
@@ -453,6 +551,27 @@ export class OpenGeniSlackBotClient {
     return await this.requireMemberChannel(headers, channelId);
   }
 
+  /**
+   * Replace one Slack user's private App Home view. `views.publish` is a
+   * naturally convergent replace operation: Slack event retries may safely
+   * repeat the exact bounded view without creating duplicate provider state.
+   */
+  async publishHomeView(input: { userId: string; blocks: SlackHomeBlock[]; hash?: string | null }) {
+    const userId = requiredSlackString(input.userId, "user_id");
+    const blocks = validateSlackHomeBlocks(input.blocks);
+    const hash = input.hash ? requiredSlackString(input.hash, "hash") : null;
+    return await this.withAudit("home.publish", async (headers) => {
+      const payload = await this.call(headers, "views.publish", {
+        user_id: userId,
+        view: JSON.stringify({ type: "home", blocks }),
+        ...(hash ? { hash } : {}),
+      });
+      return {
+        viewId: requiredSlackString(slackRecord(payload.view)?.id, "view.id"),
+      };
+    });
+  }
+
   async slackTaskPolicyFacts(channelId: string, userId: string) {
     return await this.withAudit("channel_history.read", async (headers) => {
       const conversation = await this.requireMemberChannel(headers, channelId);
@@ -649,11 +768,18 @@ export class OpenGeniSlackBotClient {
   async prepareReactionImageDownloads(input: {
     channelId: string;
     files: readonly { id: string; name: string; title: string }[];
+    authorizeSharedRead?: () => Promise<void>;
   }): Promise<PreparedSlackReactionImage[]> {
     const result = await this.withAudit("file.content.read", async (headers) => {
-      await this.requireActiveNonSharedMemberChannel(headers, input.channelId);
+      if (input.authorizeSharedRead) {
+        const channel = await this.requireMemberChannel(headers, input.channelId);
+        await authorizeSlackSharedImageRead(channel, input.authorizeSharedRead);
+      } else {
+        await this.requireActiveNonSharedMemberChannel(headers, input.channelId);
+      }
       const prepared: PreparedSlackReactionImage[] = [];
       for (const candidate of input.files) {
+        await input.authorizeSharedRead?.();
         const payload = await this.call(headers, "files.info", { file: candidate.id });
         const fileRecord = slackRecord(payload.file);
         const file = projectFile(fileRecord);
@@ -688,6 +814,7 @@ export class OpenGeniSlackBotClient {
   /** Download and fully validate one previously authorized Slack image. */
   async downloadReactionImage(
     input: PreparedSlackReactionImage,
+    authorizeSharedRead?: () => Promise<void>,
   ): Promise<DownloadedSlackReactionImage> {
     return await this.withAudit("file.content.read", async () => {
       if (!SLACK_REACTION_IMAGE_MIME_TYPES.has(input.declaredMimeType)) {
@@ -700,7 +827,11 @@ export class OpenGeniSlackBotClient {
       ) {
         throw new SlackBotProviderError("invalid_file_size");
       }
-      const response = await this.fetchPrivateFile(input.downloadUrl, "file.content.read");
+      const response = await this.fetchPrivateFile(
+        input.downloadUrl,
+        "file.content.read",
+        authorizeSharedRead,
+      );
       const responseContentType = normalizedContentType(response.headers.get("content-type"));
       if (!SLACK_REACTION_IMAGE_MIME_TYPES.has(responseContentType)) {
         await response.body?.cancel().catch(() => undefined);
@@ -748,6 +879,69 @@ export class OpenGeniSlackBotClient {
     });
   }
 
+  /**
+   * Workspace-wide public search through Slack's Real-time Search API
+   * (`assistant.search.context`) under the bot identity.
+   *
+   * The bot never carries private-search authority: `channel_types` is pinned
+   * to `public_channel` server-side regardless of caller input, so private
+   * channels, DMs, and MPIMs remain reachable only through a member's personal
+   * hosted-MCP grant. An install predating the search scopes fails closed with
+   * a reinstall hint instead of leaking Slack's `missing_scope` error.
+   */
+  async searchContext(input: {
+    query: string;
+    contentTypes?: readonly ("messages" | "files" | "channels")[];
+    includeBots?: boolean;
+    /** UNIX seconds bounds on message timestamps. */
+    before?: number;
+    after?: number;
+    sort?: "score" | "timestamp";
+    sortDir?: "asc" | "desc";
+    cursor?: string;
+    limit?: number;
+  }) {
+    const query = typeof input.query === "string" ? input.query.trim() : "";
+    if (!query || query.length > MAX_SEARCH_QUERY_CHARS) {
+      throw new SlackBotProviderError("invalid_query");
+    }
+    const contentTypes = input.contentTypes?.length
+      ? [...new Set(input.contentTypes)]
+      : ["messages"];
+    return await this.withAudit("search.context", async (headers) => {
+      // Inside the audit boundary so a fail-closed denial on a legacy install
+      // leaves the same `failed` evidence as a provider rejection.
+      if (!hasOpenGeniSlackBotSearchScopes(this.connection.grantedScopes)) {
+        throw new SlackBotProviderError("slack_bot_search_scopes_missing");
+      }
+      const payload = await this.call(headers, "assistant.search.context", {
+        query,
+        channel_types: "public_channel",
+        content_types: contentTypes.join(","),
+        ...(input.includeBots ? { include_bots: "true" } : {}),
+        ...(input.before !== undefined ? { before: String(Math.trunc(input.before)) } : {}),
+        ...(input.after !== undefined ? { after: String(Math.trunc(input.after)) } : {}),
+        ...(input.sort ? { sort: input.sort } : {}),
+        ...(input.sortDir ? { sort_dir: input.sortDir } : {}),
+        ...(input.cursor ? { cursor: input.cursor } : {}),
+        limit: String(boundedInt(input.limit, MAX_SEARCH_PAGE, MAX_SEARCH_PAGE)),
+      });
+      const results = slackRecord(payload.results);
+      return {
+        messages: slackArray(results?.messages)
+          .map(projectSearchMessage)
+          .filter((message): message is NonNullable<typeof message> => message !== null),
+        files: slackArray(results?.files)
+          .map(projectSearchFile)
+          .filter((file): file is NonNullable<typeof file> => file !== null),
+        channels: slackArray(results?.channels)
+          .map(projectSearchChannel)
+          .filter((channel): channel is NonNullable<typeof channel> => channel !== null),
+        nextCursor: responseCursor(payload),
+      };
+    });
+  }
+
   async listFiles(input: { channelId: string; limit?: number; cursor?: string }) {
     return await this.withAudit("files.list", async (headers) => {
       const requestedPage = this.fileListPage(input);
@@ -1211,10 +1405,7 @@ export class OpenGeniSlackBotClient {
   }
 
   private async slackMessageExists(channelId: string, timestamp: string): Promise<boolean> {
-    const headers = await this.headersForDestination(
-      "message.delete",
-      `${SLACK_API_BASE}chat.getPermalink`,
-    );
+    const headers = await this.headersFor("message.delete");
     try {
       await this.call(headers, "chat.getPermalink", {
         channel: channelId,
@@ -1236,7 +1427,7 @@ export class OpenGeniSlackBotClient {
     text: string;
   }): Promise<{ timestamp: string }> {
     const method = input.threadTimestamp ? "conversations.replies" : "conversations.history";
-    const headers = await this.headersForDestination("message.post", `${SLACK_API_BASE}${method}`);
+    const headers = await this.headersFor("message.post");
     const seenCursors = new Set<string>();
     let cursor: string | null = null;
     let matchedTimestamp: string | null = null;
@@ -1284,7 +1475,7 @@ export class OpenGeniSlackBotClient {
     return { timestamp: matchedTimestamp };
   }
 
-  private async requireMemberChannel(headers: Record<string, string>, channelId: string) {
+  private async requireMemberChannel(headers: SlackCallAuthority, channelId: string) {
     const payload = await this.call(headers, "conversations.info", {
       channel: channelId,
     });
@@ -1299,7 +1490,7 @@ export class OpenGeniSlackBotClient {
   }
 
   private async requireActiveNonSharedMemberChannel(
-    headers: Record<string, string>,
+    headers: SlackCallAuthority,
     channelId: string,
   ) {
     const projected = await this.requireMemberChannel(headers, channelId);
@@ -1313,7 +1504,7 @@ export class OpenGeniSlackBotClient {
   }
 
   private async requireFileForChannel(
-    headers: Record<string, string>,
+    headers: SlackCallAuthority,
     operation: "file.info" | "file.content.read",
     input: { channelId: string; fileId: string; parentFileId?: string },
   ) {
@@ -1390,11 +1581,15 @@ export class OpenGeniSlackBotClient {
   }
 
   private async call(
-    headers: Record<string, string>,
+    authority: SlackCallAuthority,
     method: string,
     params: Record<string, string>,
   ): Promise<SlackPayload> {
     try {
+      const headers = await this.headersForDestination(
+        authority.operation,
+        `${SLACK_API_BASE}${method}`,
+      );
       return (await slackApiFetchWithHeaders(this.fetchImpl, method, headers, params)).payload;
     } catch (error) {
       if (slackCredentialRejected(error)) {
@@ -1410,11 +1605,10 @@ export class OpenGeniSlackBotClient {
 
   private async withAudit<T extends Record<string, unknown>>(
     operation: SlackBotOperation,
-    run: (headers: Record<string, string>) => Promise<T>,
+    run: (authority: SlackCallAuthority) => Promise<T>,
   ): Promise<T & { receipt: SlackBotReceipt }> {
     try {
-      const headers = await this.headersFor(operation);
-      const result = await run(headers);
+      const result = await run(await this.headersFor(operation));
       await this.recordAudit(operation, "succeeded");
       return { ...result, receipt: this.receipt(operation) };
     } catch (error) {
@@ -1423,11 +1617,8 @@ export class OpenGeniSlackBotClient {
     }
   }
 
-  private async headersFor(operation: SlackBotOperation): Promise<Record<string, string>> {
-    return await this.headersForDestination(
-      operation,
-      `${SLACK_API_BASE}${slackMethodForOperation(operation)}`,
-    );
+  private async headersFor(operation: SlackBotOperation): Promise<SlackCallAuthority> {
+    return Object.freeze({ operation });
   }
 
   private async headersForDestination(
@@ -1450,14 +1641,40 @@ export class OpenGeniSlackBotClient {
     if (result.status !== "ok" || result.connectionId !== this.connection.id) {
       throw new Error("OpenGeni Slack bot connection needs to be reinstalled");
     }
+    const current = await requireOpenGeniSlackBotConnection(
+      this.db,
+      this.context.workspaceId,
+      this.connection.id,
+    );
+    const currentMetadata = openGeniSlackBotMetadata(current.metadata);
+    if (
+      current.accountId !== this.context.accountId ||
+      current.version !== this.connection.version ||
+      result.connectionVersion !== this.connection.version ||
+      !currentMetadata ||
+      currentMetadata.slackTeamId !== this.metadata.slackTeamId ||
+      currentMetadata.botId !== this.metadata.botId ||
+      currentMetadata.botUserId !== this.metadata.botUserId
+    ) {
+      throw new Error("OpenGeni Slack bot connection authority changed");
+    }
+    // The adapter callback is a fallible preflight. The canonical credential
+    // callback must remain the final await before the physical fetch.
+    if (this.authorizeProviderRequest && (await this.authorizeProviderRequest()) === false) {
+      throw new Error("OpenGeni Slack bot provider request is no longer authorized");
+    }
+    if (result.authorizeProviderRequest && !(await result.authorizeProviderRequest())) {
+      throw new Error("OpenGeni Slack bot provider request is no longer authorized");
+    }
     return result.headers;
   }
 
   private async fetchPrivateFile(
     url: URL,
     operation: "file.info" | "file.content.read",
+    authorizeBeforeFetch?: () => Promise<void>,
   ): Promise<Response> {
-    const response = await this.fetchPrivateFileOnce(url, operation);
+    const response = await this.fetchPrivateFileOnce(url, operation, authorizeBeforeFetch);
     if (response.status < 300 || response.status >= 400) {
       return response;
     }
@@ -1478,18 +1695,20 @@ export class OpenGeniSlackBotClient {
     } catch {
       throw new SlackBotProviderError("invalid_file_redirect");
     }
-    return await this.fetchPrivateFileOnce(redirected, operation);
+    return await this.fetchPrivateFileOnce(redirected, operation, authorizeBeforeFetch);
   }
 
   private async fetchPrivateFileOnce(
     url: URL,
     operation: "file.info" | "file.content.read",
+    authorizeBeforeFetch?: () => Promise<void>,
   ): Promise<Response> {
     try {
       assertPrivateSlackFileUrl(url);
     } catch {
       throw new SlackBotProviderError("invalid_file_url");
     }
+    await authorizeBeforeFetch?.();
     const headers = await this.headersForDestination(operation, url.toString());
     let response: Response;
     try {
@@ -1701,7 +1920,12 @@ export class OpenGeniSlackBotClient {
 }
 
 export function createOpenGeniSlackBotClient(
-  deps: { db: Database; settings: Settings; slackFetch?: typeof fetch },
+  deps: {
+    db: Database;
+    settings: Settings;
+    slackFetch?: typeof fetch;
+    authorizeProviderRequest?: SlackProviderAuthorization;
+  },
   resolved: Awaited<ReturnType<typeof resolveSlackBotConnectionForTool>>,
 ): OpenGeniSlackBotClient {
   return new OpenGeniSlackBotClient(
@@ -1711,11 +1935,17 @@ export function createOpenGeniSlackBotClient(
     resolved.metadata,
     resolved.context,
     deps.slackFetch,
+    deps.authorizeProviderRequest,
   );
 }
 
 export async function createOpenGeniSlackBotInteractionClient(
-  deps: { db: Database; settings: Settings; slackFetch?: typeof fetch },
+  deps: {
+    db: Database;
+    settings: Settings;
+    slackFetch?: typeof fetch;
+    authorizeProviderRequest?: SlackProviderAuthorization;
+  },
   input: {
     accountId: string;
     workspaceId: string;
@@ -1747,6 +1977,7 @@ export async function createOpenGeniSlackBotInteractionClient(
       scheduledTaskId: null,
     },
     deps.slackFetch,
+    deps.authorizeProviderRequest,
   );
 }
 
@@ -1770,7 +2001,7 @@ async function slackApiFetchWithHeaders(
   credentialHeaders: Record<string, string>,
   params: Record<string, string>,
 ): Promise<{ response: Response; payload: SlackPayload }> {
-  if (!/^[a-z]+\.[a-z]+$/i.test(method)) {
+  if (!/^[a-z]+(?:\.[a-z]+){1,2}$/i.test(method)) {
     throw new Error("invalid Slack API method");
   }
   const url = new URL(method, SLACK_API_BASE);
@@ -2576,6 +2807,74 @@ function embeddedSlackFileIds(content: string): Set<string> {
   );
 }
 
+/**
+ * Bounded projections of `assistant.search.context` results. Content excerpts
+ * are capped, Slack's rich `blocks` and context messages are deliberately
+ * dropped, and permalinks are kept only when they are https URLs.
+ */
+function projectSearchMessage(value: unknown) {
+  const message = slackRecord(value);
+  const channelId = slackString(message?.channel_id);
+  const ts = slackString(message?.message_ts);
+  if (!message || !channelId || !ts) return null;
+  return {
+    channelId,
+    channelName: boundedSlackString(message.channel_name, 256),
+    ts,
+    authorUserId: boundedSlackString(message.author_user_id, 64),
+    authorName: boundedSlackString(message.author_name, 256),
+    isAuthorBot: message.is_author_bot === true,
+    content: boundedSlackString(message.content, MAX_SEARCH_CONTENT_CHARS),
+    permalink: safeSlackPermalink(message.permalink),
+  };
+}
+
+function projectSearchFile(value: unknown) {
+  const file = slackRecord(value);
+  const id = slackString(file?.file_id);
+  if (!file || !id) return null;
+  return {
+    id,
+    title: boundedSlackString(file.title, 512),
+    filetype: boundedSlackString(file.file_type, 128),
+    authorUserId: boundedSlackString(file.author_user_id, 64),
+    authorName: boundedSlackString(file.author_name, 256),
+    dateCreated: slackUnixSeconds(file.date_created),
+    dateUpdated: slackUnixSeconds(file.date_updated),
+    content: boundedSlackString(file.content, MAX_SEARCH_CONTENT_CHARS),
+    permalink: safeSlackPermalink(file.permalink),
+  };
+}
+
+function projectSearchChannel(value: unknown) {
+  const channel = slackRecord(value);
+  const name = slackString(channel?.name);
+  if (!channel || !name) return null;
+  return {
+    name: boundedSlackString(name, 256),
+    topic: boundedSlackString(channel.topic, 512),
+    purpose: boundedSlackString(channel.purpose, 512),
+    creatorUserId: boundedSlackString(channel.creator_user_id, 64),
+    dateCreated: slackUnixSeconds(channel.date_created),
+    permalink: safeSlackPermalink(channel.permalink),
+  };
+}
+
+function slackUnixSeconds(value: unknown): number | null {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+function safeSlackPermalink(value: unknown): string | null {
+  // An over-long URL is dropped, never truncated into a still-parseable one.
+  const raw = typeof value === "string" && value.length <= 1_024 ? value : "";
+  if (!raw) return null;
+  try {
+    return new URL(raw).protocol === "https:" ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
 function projectUser(value: unknown) {
   const user = slackRecord(value);
   const id = slackString(user?.id);
@@ -2701,30 +3000,6 @@ export function nextSlackFilesListPage(
   return nextPage;
 }
 
-function slackMethodForOperation(operation: SlackBotOperation): string {
-  switch (operation) {
-    case "channels.list":
-      return "conversations.list";
-    case "channel_history.read":
-      return "conversations.history";
-    case "thread_replies.read":
-      return "conversations.replies";
-    case "users.list":
-      return "users.list";
-    case "files.list":
-      return "files.list";
-    case "file.info":
-    case "file.content.read":
-      return "files.info";
-    case "message.post":
-      return "chat.postMessage";
-    case "message.update":
-      return "chat.update";
-    case "message.delete":
-      return "chat.delete";
-  }
-}
-
 function validateSlackMessageBlocks(
   blocks: SlackMessageBlock[] | undefined,
 ): SlackMessageBlock[] | undefined {
@@ -2738,6 +3013,16 @@ function validateSlackMessageBlocks(
   return blocks;
 }
 
+function validateSlackHomeBlocks(blocks: SlackHomeBlock[]): SlackHomeBlock[] {
+  if (blocks.length < 1 || blocks.length > 100) {
+    throw new RangeError("Slack App Home blocks exceed the supported count");
+  }
+  if (Buffer.byteLength(JSON.stringify(blocks), "utf8") > 48 * 1024) {
+    throw new RangeError("Slack App Home blocks exceed the supported byte size");
+  }
+  return blocks;
+}
+
 function boundedInt(value: number | undefined, max: number, fallback: number): number {
   return typeof value === "number" && Number.isInteger(value) && value > 0
     ? Math.min(value, max)