@open-everywhere/provider-slack 0.4.0 → 0.5.0

package/agent/channels/slack-home.ts

@@ -0,0 +1,511 @@
+// THE SLACK APP HOME TAB (OPE-2451) — the person's own page: what the agent remembers about them,
+// what their domains know, and (OPE-2456, later) their rules. Core owns the page model
+// (`home/home-view.ts`); this module is the Slack half: it parses the three Slack deliveries the
+// page needs, builds the VERIFIED viewer, renders Block Kit, and drives the dialogs.
+//
+// THE THREE DELIVERIES, all classified by the front route (slack-front.ts) and never forwarded:
+//   • `app_home_opened` (Events API, `tab: "home"`) → build the viewer, `views.publish` the page.
+//   • a `block_actions` whose action id starts `oe_home:` → a button (Export, Refresh) runs at once;
+//     an item's overflow choice (Edit, Forget) opens a modal.
+//   • a `view_submission` whose `callback_id` is {@link HOME_MODAL_CALLBACK_ID} → run the action the
+//     modal named, then publish the page again with a one-line notice.
+//
+// 🔴 THE VIEWER COMES FROM THE SIGNED ENVELOPE, NEVER FROM A FIELD WE WROTE. The page is private to
+// one person because Slack shows each person their own Home tab, and that only holds if every read
+// and every write is keyed to the person Slack says is looking. So the viewer is built from the
+// event's `user` / the interaction's `user.id` and `team`, every time. A modal's `private_metadata`
+// carries ONLY the action id and the line digest — never a user, a channel, a partition or a silo —
+// and core looks the digest up inside the viewer's own memory, so a forged digest names nothing the
+// clicker does not already own.
+//
+// 🔴 THE TRUST GATE, APPLIED TO A PERSON. A domain's memory is internal knowledge. The page lists a
+// domain only when the viewer is a full member of the workspace (`users.info`, fail-closed) AND sits
+// in one of the domain's channels that Slack confirms is internal (`conversations.info`, fail-closed).
+// A guest, or a person whose only route into a domain is a Slack Connect channel, sees their own
+// memory and no domain's.
+
+import {
+  appendAudit,
+  bindFrom,
+  buildHomeView,
+  domainForChannel,
+  getConfig,
+  hasHomeAction,
+  homeDomainsFor,
+  resolvePartition,
+  runHomeAction,
+  SLACK_HOME_WIRE,
+  type BindableContext,
+  type HomeBlock,
+  type HomeDomainMembership,
+  type HomeViewer,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { slackInteractivityTenantIds } from "./slack-tenant-fence.js";
+import { confirmChannelInternal, slackAuthorIsMember, slackForm } from "./slack-events.js";
+import { encodeSlackForm } from "./slack-web-api.js";
+
+// ── WIRE CONSTANTS ──────────────────────────────────────────────────────────────────────────────
+
+/** Every Home-tab action id starts with this, so the front route can claim it without reading on. */
+export const HOME_ACTION_PREFIX = SLACK_HOME_WIRE.actionPrefix;
+/** The one modal the Home tab opens. Its `callback_id` is how the front route claims a submission. */
+export const HOME_MODAL_CALLBACK_ID = SLACK_HOME_WIRE.modalCallbackId;
+/** The block and element ids of the modal's text input (the Edit dialog). */
+const EDIT_BLOCK_ID = "oe_home_edit";
+const EDIT_ELEMENT_ID = "text";
+/** Slack refuses a view with more than 100 blocks. The renderer stops below it and says so. */
+export const SLACK_HOME_MAX_BLOCKS = 100;
+/** A section block's text is capped at 3000 characters by Slack. An item is cut well below that. */
+const ITEM_TEXT_MAX = 600;
+/** How many of the viewer's channels the domain lookup pages through (200 per page). */
+const MEMBERSHIP_PAGES_MAX = 5;
+
+// ── PARSING (pure) ──────────────────────────────────────────────────────────────────────────────
+
+export interface ParsedHomeOpen {
+  readonly teamId?: string;
+  readonly enterpriseId?: string;
+  readonly userId: string;
+}
+
+/**
+ * An `app_home_opened` event for the HOME tab, or undefined. The same event fires when a person
+ * opens the Messages tab (`tab: "messages"`), and that one is not ours to answer — publishing the
+ * page on every DM open would cost a full build for a tab the person is not looking at.
+ */
+export function parseHomeOpened(env: unknown): ParsedHomeOpen | undefined {
+  const e = asObject(env);
+  const ev = asObject(e?.event);
+  if (e?.type !== "event_callback" || ev?.type !== "app_home_opened" || ev.tab !== "home") return undefined;
+  const userId = str(ev.user);
+  if (!userId) return undefined;
+  const teamId = str(e.team_id);
+  const enterpriseId = str(e.enterprise_id);
+  return { userId, ...(teamId ? { teamId } : {}), ...(enterpriseId ? { enterpriseId } : {}) };
+}
+
+export interface ParsedHomeInteraction {
+  readonly userId: string;
+  readonly teamId?: string;
+  readonly enterpriseId?: string;
+  readonly triggerId?: string;
+}
+
+export interface ParsedHomeClick extends ParsedHomeInteraction {
+  /** The core action id (`memory.forget`), with the wire prefix removed. */
+  readonly action: string;
+  /** The item digest an overflow choice carries. Absent on a button. */
+  readonly ref?: string;
+}
+
+export interface ParsedHomeSubmission extends ParsedHomeInteraction {
+  readonly action: string;
+  readonly ref?: string;
+  /** The Edit dialog's new text. Absent on a confirmation. */
+  readonly input?: string;
+}
+
+function interactionIds(p: Record<string, unknown>): ParsedHomeInteraction | undefined {
+  const userId = str(asObject(p.user)?.id);
+  if (!userId) return undefined;
+  const { teamId, enterpriseId } = slackInteractivityTenantIds(p);
+  const triggerId = str(p.trigger_id);
+  return { userId, ...(teamId ? { teamId } : {}), ...(enterpriseId ? { enterpriseId } : {}), ...(triggerId ? { triggerId } : {}) };
+}
+
+/**
+ * A Home-tab `block_actions` click, or undefined. A BUTTON names its action in the action id
+ * (`oe_home:memory.export`). An item's OVERFLOW names it in the chosen option's value
+ * (`memory.forget|<digest>`), because one overflow carries both of an item's actions.
+ */
+export function parseHomeClick(raw: unknown): ParsedHomeClick | undefined {
+  const p = asObject(raw);
+  if (p?.type !== "block_actions" || !Array.isArray(p.actions)) return undefined;
+  const ids = interactionIds(p);
+  if (!ids) return undefined;
+  for (const a of p.actions) {
+    const act = asObject(a);
+    const actionId = str(act?.action_id);
+    if (!actionId?.startsWith(HOME_ACTION_PREFIX)) continue;
+    if (act?.type === "overflow") {
+      const value = str(asObject(act.selected_option)?.value);
+      const split = value ? splitActionValue(value) : undefined;
+      if (split) return { ...ids, ...split };
+      continue;
+    }
+    const action = actionId.slice(HOME_ACTION_PREFIX.length);
+    if (action) return { ...ids, action };
+  }
+  return undefined;
+}
+
+/** A submission of the Home tab's own modal, or undefined for any other view. */
+export function parseHomeSubmission(raw: unknown): ParsedHomeSubmission | undefined {
+  const p = asObject(raw);
+  if (p?.type !== "view_submission") return undefined;
+  const view = asObject(p.view);
+  if (view?.callback_id !== HOME_MODAL_CALLBACK_ID) return undefined;
+  const ids = interactionIds(p);
+  if (!ids) return undefined;
+  const meta = str(view.private_metadata);
+  const split = meta ? splitActionValue(meta) : undefined;
+  if (!split) return undefined;
+  const values = asObject(asObject(view.state)?.values);
+  const input = str(asObject(asObject(values?.[EDIT_BLOCK_ID])?.[EDIT_ELEMENT_ID])?.value);
+  return { ...ids, ...split, ...(input !== undefined ? { input } : {}) };
+}
+
+/** `action|ref` → its parts. The ref, when present, must look like a line digest. PURE. */
+function splitActionValue(value: string): { action: string; ref?: string } | undefined {
+  const bar = value.indexOf("|");
+  const action = bar === -1 ? value : value.slice(0, bar);
+  const ref = bar === -1 ? undefined : value.slice(bar + 1);
+  if (!/^[a-z][a-z0-9._-]{0,63}$/.test(action)) return undefined;
+  if (ref !== undefined && !/^[0-9a-f]{64}$/.test(ref)) return undefined;
+  return { action, ...(ref !== undefined ? { ref } : {}) };
+}
+
+// ── RENDERING (pure) ────────────────────────────────────────────────────────────────────────────
+
+/** Escape the three characters Slack's mrkdwn treats as control. Memory lines are member-authored,
+ *  and an unescaped `<!channel>` or `<@U…>` in one would ping a room from a private page. */
+export function escapeSlackText(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function clip(text: string, max: number): string {
+  return text.length <= max ? text : text.slice(0, max - 1) + "…";
+}
+
+type SlackBlock = Record<string, unknown>;
+
+function plain(text: string): Record<string, unknown> {
+  return { type: "plain_text", text: clip(text, 150), emoji: true };
+}
+
+/** One neutral block → Slack blocks. */
+function renderBlock(b: HomeBlock): SlackBlock[] {
+  switch (b.kind) {
+    case "heading":
+      return [{ type: "header", text: plain(b.text) }];
+    case "text":
+      return [{ type: "section", text: { type: "mrkdwn", text: escapeSlackText(clip(b.text, 2900)) } }];
+    case "note":
+      return [{ type: "context", elements: [{ type: "mrkdwn", text: escapeSlackText(clip(b.text, 2900)) }] }];
+    case "divider":
+      return [{ type: "divider" }];
+    case "buttons":
+      return [
+        {
+          type: "actions",
+          elements: b.buttons.map((btn) => ({ type: "button", action_id: `${HOME_ACTION_PREFIX}${btn.id}`, text: plain(btn.label) })),
+        },
+      ];
+    case "room":
+      return [{ type: "context", elements: [{ type: "mrkdwn", text: `${escapeSlackText(b.text)} <#${b.room.nativeId}>` }] }];
+    case "item": {
+      const label = b.label ? `*${escapeSlackText(clip(b.label, 80))}* · ` : "";
+      const section: SlackBlock = { type: "section", text: { type: "mrkdwn", text: label + escapeSlackText(clip(b.text, ITEM_TEXT_MAX)) } };
+      if (b.ref && b.actions.length > 0) {
+        section.accessory = {
+          type: "overflow",
+          action_id: `${HOME_ACTION_PREFIX}item`,
+          options: b.actions.map((a) => ({ text: plain(a.label), value: `${a.id}|${b.ref}` })),
+        };
+      }
+      return [section];
+    }
+  }
+}
+
+/**
+ * The whole Home view as Slack Block Kit. PURE.
+ *
+ * 🔴 THE 100-BLOCK CAP IS SLACK'S, AND A VIEW OVER IT IS REFUSED WHOLE. A refused publish leaves the
+ * person looking at a stale page with no word of why, so the renderer stops two blocks short of the
+ * cap and closes with a line that says the page was cut and Export carries the rest.
+ */
+export function renderHomeView(sections: readonly { readonly blocks: readonly HomeBlock[] }[], notice?: string): { type: "home"; blocks: SlackBlock[] } {
+  const blocks: SlackBlock[] = [];
+  if (notice) blocks.push({ type: "section", text: { type: "mrkdwn", text: `:information_source: ${escapeSlackText(clip(notice, 2900))}` } });
+  const room = SLACK_HOME_MAX_BLOCKS - 1;
+  let cut = false;
+  outer: for (const s of sections) {
+    for (const b of s.blocks) {
+      const rendered = renderBlock(b);
+      if (blocks.length + rendered.length > room) {
+        cut = true;
+        break outer;
+      }
+      blocks.push(...rendered);
+    }
+  }
+  if (cut) blocks.push({ type: "context", elements: [{ type: "mrkdwn", text: "This page is full, so some lines are not shown. Export gives you everything in your memory." }] });
+  return { type: "home", blocks };
+}
+
+/** The modal an item's overflow choice opens. `edit` asks for the new text, `confirm` asks for a yes. */
+function homeActionModal(input: {
+  readonly action: string;
+  readonly ref: string;
+  readonly kind: "edit" | "confirm";
+  readonly itemText: string;
+  readonly title: string;
+  readonly yes: string;
+}): Record<string, unknown> {
+  const quoted = escapeSlackText(clip(input.itemText, 2800));
+  return {
+    type: "modal",
+    callback_id: HOME_MODAL_CALLBACK_ID,
+    private_metadata: `${input.action}|${input.ref}`,
+    title: plain(clip(input.title, 24)),
+    submit: plain(clip(input.yes, 24)),
+    close: plain("Cancel"),
+    blocks:
+      input.kind === "edit"
+        ? [
+            {
+              type: "input",
+              block_id: EDIT_BLOCK_ID,
+              label: plain("The fact, as I should remember it"),
+              element: { type: "plain_text_input", action_id: EDIT_ELEMENT_ID, initial_value: clip(input.itemText, 1000), max_length: 1000 },
+            },
+            { type: "context", elements: [{ type: "mrkdwn", text: "The audit log records that this line changed, by fingerprint — never the words." }] },
+          ]
+        : [
+            { type: "section", text: { type: "mrkdwn", text: `> ${quoted}` } },
+            { type: "context", elements: [{ type: "mrkdwn", text: "I remove this line from your memory everywhere it is stored. You cannot undo it." }] },
+          ],
+  };
+}
+
+// ── THE VIEWER ──────────────────────────────────────────────────────────────────────────────────
+
+/** The Slack calls the viewer needs. Injected so the gate is tested without Slack. */
+export interface SlackHomeDeps {
+  /** One Slack Web API call; undefined on any failure (fail-soft, like `slackForm`). */
+  readonly call: (method: string, body: Record<string, unknown>) => Promise<Record<string, unknown> | undefined>;
+  /** Is this person a full member of the workspace? undefined when the lookup failed. */
+  readonly authorIsMember: (userId: string, teamId: string | undefined) => Promise<boolean | undefined>;
+  /** Is this channel confirmed internal? false on any doubt. */
+  readonly channelInternal: (channelId: string) => Promise<boolean>;
+}
+
+/** The live deps: every call through `slackForm` (the one Web API seam, fail-soft), the shared member
+ *  probe, and the shared fail-closed channel gate. */
+export function liveSlackHomeDeps(): SlackHomeDeps {
+  return {
+    call: (method, body) => slackForm(method, encodeSlackForm(body)),
+    authorIsMember: slackAuthorIsMember,
+    channelInternal: confirmChannelInternal,
+  };
+}
+
+/** The BindableContext a person's own DM resolves to — the SAME shape a DM wake binds with, so the
+ *  partition (org, workspace, surface) is the one the DM's memory was written under. */
+function dmBindable(ids: { teamId?: string; userId: string; channelId: string }): BindableContext {
+  return {
+    channel: { kind: "slack" },
+    session: {
+      auth: {
+        current: {
+          attributes: { team_id: ids.teamId ?? "", channel_id: ids.channelId, channel_type: "im" },
+          principalId: ids.userId,
+          principalType: "slack-user",
+        },
+      },
+    },
+  } as BindableContext;
+}
+
+/**
+ * Build the VERIFIED viewer for one Slack person. Every input is from the signed envelope.
+ *
+ *   • the personal partition: `conversations.open` with the person names THEIR DM with the app,
+ *     the same `D…` their DM wakes bind to. On failure the personal section says it could not load.
+ *   • trust: `users.info` through the shared member probe. Unresolvable ⇒ external (fail-closed).
+ *   • domains (internal viewers only): the channels Slack lists for the person, mapped to a domain
+ *     through the SAME router a wake uses, kept only where Slack confirms the channel internal.
+ */
+export async function buildSlackHomeViewer(ids: ParsedHomeInteraction, deps: SlackHomeDeps): Promise<HomeViewer | undefined> {
+  const opened = await deps.call("conversations.open", { users: ids.userId });
+  const dmId = opened?.ok === true ? str(asObject(opened.channel)?.id) : undefined;
+  const anchor = dmBindable({ ...ids, channelId: dmId ?? "home" });
+  const binding = bindFrom(anchor);
+  if (!binding.principalId) return undefined;
+  const partition = resolvePartition(anchor);
+  const member = await deps.authorIsMember(ids.userId, ids.teamId);
+  const trust: "internal" | "external" = member === true ? "internal" : "external";
+  const memberships = trust === "internal" ? await slackDomainMemberships(ids.userId, partition.workspaceKey, deps) : [];
+  return {
+    org: partition.org,
+    platform: partition.platform,
+    workspace: partition.workspace,
+    principalId: binding.principalId,
+    ...(dmId ? { personal: partition } : {}),
+    trust,
+    domains: homeDomainsFor(trust, memberships),
+  };
+}
+
+/** The domains a person belongs to through an internal channel. Fail-soft: a failed page ends the walk. */
+async function slackDomainMemberships(userId: string, workspaceKey: string, deps: SlackHomeDeps): Promise<HomeDomainMembership[]> {
+  const domains = getConfig().loadDomains();
+  const byDomain = new Map<string, HomeDomainMembership>();
+  let cursor: string | undefined;
+  for (let page = 0; page < MEMBERSHIP_PAGES_MAX; page++) {
+    const res = await deps.call("users.conversations", {
+      user: userId,
+      types: "public_channel,private_channel",
+      exclude_archived: true,
+      limit: 200,
+      ...(cursor ? { cursor } : {}),
+    });
+    if (res?.ok !== true || !Array.isArray(res.channels)) break;
+    for (const c of res.channels) {
+      const channelId = str(asObject(c)?.id);
+      if (!channelId) continue;
+      const surfaceKey = `${workspaceKey}/${channelId}`;
+      const domain = domainForChannel(surfaceKey, domains);
+      if (!domain || domain.memory === undefined) continue;
+      if (!(await deps.channelInternal(channelId))) continue;
+      const existing = byDomain.get(domain.name);
+      const room = { surfaceKey, nativeId: channelId };
+      byDomain.set(domain.name, existing ? { domain, rooms: [...existing.rooms, room] } : { domain, rooms: [room] });
+    }
+    cursor = str(asObject(res.response_metadata)?.next_cursor);
+    if (!cursor) break;
+  }
+  return [...byDomain.values()];
+}
+
+// ── THE THREE HANDLERS ──────────────────────────────────────────────────────────────────────────
+
+/** The audit action every publish attempt writes. Declared in core's registry (operational). */
+const HOME_PUBLISH_ACTION = "home.publish";
+
+/**
+ * Publish the page for one viewer, with an optional notice at the top, and write one `home.publish`
+ * row. The row is how a reader outside Slack (the e2e board, an operator) learns the page reached a
+ * person: Slack offers no API to read another person's Home tab back. It carries counts and Slack's
+ * error code only — never a line of the page.
+ */
+async function publishHome(userId: string, viewer: HomeViewer, deps: SlackHomeDeps, notice?: string): Promise<boolean> {
+  const view = renderHomeView(await buildHomeView(viewer), notice);
+  const res = await deps.call("views.publish", { user_id: userId, view });
+  const ok = res?.ok === true;
+  if (!ok) console.log(`[open-everywhere:slack-home] views.publish failed: ${String(res?.error ?? "no response")}`);
+  await appendAudit({
+    org: viewer.org,
+    platform: viewer.platform,
+    workspace: viewer.workspace,
+    surface: viewer.personal?.surface ?? "home",
+    principalId: viewer.principalId,
+    action: HOME_PUBLISH_ACTION,
+    detail: {
+      ok,
+      blocks: view.blocks.length,
+      trust: viewer.trust,
+      domains: viewer.domains.length,
+      notice: notice !== undefined,
+      ...(ok ? {} : { error: typeof res?.error === "string" ? res.error : "no response" }),
+    },
+  }).catch(() => undefined);
+  return ok;
+}
+
+/** `app_home_opened` → build the viewer, publish the page. */
+export async function handleHomeOpened(ev: ParsedHomeOpen, deps: SlackHomeDeps): Promise<boolean> {
+  const viewer = await buildSlackHomeViewer(ev, deps);
+  if (!viewer) return false;
+  return publishHome(ev.userId, viewer, deps);
+}
+
+/**
+ * A Home-tab click. A button runs its action and republishes. An overflow choice opens the action's
+ * modal — the item text it quotes is read from the VIEWER's own page model, never from the payload,
+ * so a forged digest that names no line of theirs opens nothing.
+ */
+export async function handleHomeClick(click: ParsedHomeClick, deps: SlackHomeDeps): Promise<boolean> {
+  if (!hasHomeAction(click.action)) return false;
+  const viewer = await buildSlackHomeViewer(click, deps);
+  if (!viewer) return false;
+  if (click.ref === undefined) {
+    const result = await runHomeAction(viewer, click.action);
+    if (result.file) await deliverFile(click.userId, result.file, result.notice, deps);
+    const notice = result.file ? `${result.notice} I sent it to our direct messages.` : result.notice;
+    return publishHome(click.userId, viewer, deps, notice || undefined);
+  }
+  const located = await locateItem(viewer, click.action, click.ref);
+  if (!located || !click.triggerId) {
+    return publishHome(click.userId, viewer, deps, "That line is not on your page any more.");
+  }
+  const res = await deps.call("views.open", {
+    trigger_id: click.triggerId,
+    view: homeActionModal({
+      action: click.action,
+      ref: click.ref,
+      kind: located.action.kind,
+      itemText: located.text,
+      title: located.action.confirm?.title ?? `${located.action.label}`,
+      yes: located.action.confirm?.yes ?? "Save",
+    }),
+  });
+  return res?.ok === true;
+}
+
+/** Find the item a digest names on the VIEWER's own page, and the action it offers. */
+async function locateItem(viewer: HomeViewer, actionId: string, ref: string) {
+  for (const section of await buildHomeView(viewer)) {
+    for (const b of section.blocks) {
+      if (b.kind !== "item" || b.ref !== ref) continue;
+      const action = b.actions.find((a) => a.id === actionId);
+      if (action) return { text: b.text, action };
+    }
+  }
+  return undefined;
+}
+
+/** A Home modal's submission → run the action, republish with its notice. */
+export async function handleHomeSubmission(sub: ParsedHomeSubmission, deps: SlackHomeDeps): Promise<boolean> {
+  if (!hasHomeAction(sub.action)) return false;
+  const viewer = await buildSlackHomeViewer(sub, deps);
+  if (!viewer) return false;
+  const result = await runHomeAction(viewer, sub.action, sub.ref, sub.input);
+  return publishHome(sub.userId, viewer, deps, result.notice || undefined);
+}
+
+/** Hand a document to the person: upload it into their DM with the app (Slack's external upload). */
+async function deliverFile(
+  userId: string,
+  file: { readonly filename: string; readonly title: string; readonly content: string },
+  comment: string,
+  deps: SlackHomeDeps,
+): Promise<boolean> {
+  const opened = await deps.call("conversations.open", { users: userId });
+  const channelId = opened?.ok === true ? str(asObject(opened.channel)?.id) : undefined;
+  if (!channelId) return false;
+  const bytes = new TextEncoder().encode(file.content);
+  const url = await deps.call("files.getUploadURLExternal", { filename: file.filename, length: bytes.byteLength });
+  const uploadUrl = url?.ok === true ? str(url.upload_url) : undefined;
+  const fileId = url?.ok === true ? str(url.file_id) : undefined;
+  if (!uploadUrl || !fileId) return false;
+  const put = await fetch(uploadUrl, { method: "POST", headers: { "content-type": "text/markdown" }, body: bytes }).catch(() => undefined);
+  if (!put?.ok) return false;
+  const done = await deps.call("files.completeUploadExternal", {
+    files: [{ id: fileId, title: file.title }],
+    channel_id: channelId,
+    initial_comment: comment,
+  });
+  return done?.ok === true;
+}
+
+// ── helpers ─────────────────────────────────────────────────────────────────────────────────────
+
+function asObject(v: unknown): Record<string, unknown> | undefined {
+  return typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}