@zksecurity/slack-events 0.1.1 → 0.2.0

package/README.md

@@ -57,3 +57,39 @@ npm pack ./packages/slack-events
 The prepack step compiles only the dependency-free client source. Inspect and
 test the tarball before publishing it with `npm publish TARBALL` under an
 authorized npm account. Publishing is independent of the bot's npm package.
+
+## Read Slack context and download files
+
+After deploying the matching server and reauthorizing the expanded user scopes:
+
+```sh
+slack-events users
+slack-events channels
+slack-events channels --limit 200 --cursor NEXT_CURSOR
+slack-events user U012345
+slack-events channel C012345
+slack-events message C012345 1788884385.665039
+slack-events history C012345 --limit 50 --cursor NEXT_CURSOR
+slack-events thread C012345 1788881468.871969 --limit 50
+slack-events file F012345
+slack-events download F012345 ./attachment.pdf
+slack-events listen --resolve
+```
+
+Use `users` and `channels` to discover IDs before making individual reads. They return Slack JSON with `members` or `channels` arrays containing IDs and names. `channels` includes public/private channels and direct/group conversations available to your user grant. Follow `response_metadata.next_cursor` with `--cursor` until it is empty; each call returns one page, and `--limit` accepts 1-200. The existing `list` command lists feed subscriptions, not Slack conversations.
+
+Slack identifies a thread by its channel ID and root message timestamp, not a separate thread ID. Use `history CHANNEL_ID` to find a root message's `ts`, then run `thread CHANNEL_ID ROOT_TS`. If you have a reply, its `thread_ts` identifies the root; use `message CHANNEL_ID MESSAGE_TS` to inspect it when needed. Keep timestamps as strings with all decimal digits.
+
+Read commands return Slack JSON, including pagination cursors. `message` returns
+one target message and its reactions through `reactions.get`; `thread` takes the
+parent timestamp. Download streams file bytes via the event server using the
+subscriber's user grant, refuses to overwrite existing paths, and writes mode
+0600. External files without a Slack-hosted download are unsupported. A failed
+transfer may leave a partial output file; remove that file before retrying.
+
+`listen --resolve` adds `context.users` / `context.channels` name maps while preserving the original event and cursor. It fetches a complete user and conversation name snapshot in the background at startup and every six hours, caching the entire snapshot in memory until the next successful refresh. Failed refreshes keep the previous snapshot; unknown names fall back to IDs without blocking delivery. Restarting the listener fetches a fresh snapshot. Standalone file shares also get `context.files` metadata, fetched separately with a two-second deadline; failure leaves the original event intact and the files list empty. Use `file` or `download` to retry retrieving the file.
+No read command changes the ACK cursor. The CLI uses its existing paired feed
+credential; Slack user tokens stay on the server. No bot credential is used.
+
+The packaged [slack-events skill](skills/slack-events/SKILL.md) is a manual for
+agents consuming these events and using the CLI.

package/dist/cli.js

@@ -1,8 +1,20 @@
-import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync, createWriteStream } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 export async function runSlackEventsCli(args) {
-    const usage = "Usage: slack-events pair <server> [code] | listen | ack <committed-cursor> | list | revoke <subscription-id>";
+    const usage = `Usage: slack-events pair <server> [code] | listen [--resolve] | ack <committed-cursor> | list | revoke <subscription-id>
+  users [--limit N] [--cursor C]      List users and their IDs
+  channels [--limit N] [--cursor C]   List conversations and their IDs
+  user USER_ID                       Get user profile/name
+  channel CHANNEL_ID                 Get channel metadata/name
+  history CHANNEL_ID [--limit N] [--cursor C]
+  thread CHANNEL_ID TIMESTAMP [--limit N] [--cursor C]
+  message CHANNEL_ID TIMESTAMP        Get one message
+  file FILE_ID                       Get file metadata and Slack links
+  download FILE_ID OUTPUT_PATH       Download a file (refuses overwrite)
+Read commands print Slack JSON including pagination cursors. They never ACK events.`;
     const command = args[0];
     if (!command || command === "--help" || command === "-h") {
         process.stdout.write(`${usage}\n`);
@@ -19,6 +31,52 @@ export async function runSlackEventsCli(args) {
         return;
     }
     const credential = readCredential();
+    if (["user", "users", "channel", "channels", "history", "thread", "message", "file", "download"].includes(command)) {
+        const query = new URLSearchParams();
+        let position = 1;
+        if (command !== "users" && command !== "channels") {
+            const id = requireArgument(args[position++], "Slack ID");
+            if (!/^[A-Z][A-Z0-9]+$/.test(id))
+                throw new Error("Invalid Slack ID");
+            query.set("id", id);
+        }
+        if (command === "thread" || command === "message") {
+            const ts = requireArgument(args[position++], "message timestamp");
+            if (!/^\d+\.\d+$/.test(ts))
+                throw new Error("Invalid Slack timestamp");
+            query.set("ts", ts);
+        }
+        if (command === "download") {
+            const output = requireArgument(args[position++], "output path");
+            if (position !== args.length)
+                throw new Error(usage);
+            const response = await fetch(new URL(`/v1/events/slack/download?${query}`, credential.server), {
+                headers: { authorization: `Bearer ${credential.token}` }, signal: AbortSignal.timeout(120_000), redirect: "error",
+            });
+            if (!response.ok) {
+                const error = await response.json();
+                throw new Error(error.error || `Download failed (${response.status})`);
+            }
+            if (!response.body)
+                throw new Error("Download response has no body");
+            // wx prevents overwriting an existing file or following an existing symlink.
+            await pipeline(Readable.fromWeb(response.body), createWriteStream(output, { flags: "wx", mode: 0o600 }));
+            process.stdout.write(`${output}\n`);
+            return;
+        }
+        while (position < args.length) {
+            const option = args[position++];
+            if (!["users", "channels", "history", "thread"].includes(command) || !["--limit", "--cursor"].includes(option))
+                throw new Error(usage);
+            const value = requireArgument(args[position++], option);
+            if (option === "--limit" && (!/^\d+$/.test(value) || Number(value) < 1 || Number(value) > 200))
+                throw new Error("limit must be between 1 and 200");
+            query.set(option.slice(2), value);
+        }
+        const result = await request(credential.server, `/v1/events/slack/${command}?${query}`, { token: credential.token });
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
     if (command === "ack") {
         const value = requireArgument(args[1], "committed cursor");
         const cursor = Number(value);
@@ -42,7 +100,9 @@ export async function runSlackEventsCli(args) {
         return;
     }
     if (command === "listen") {
-        await listen(credential);
+        if (args.length > 2 || (args[1] && args[1] !== "--resolve"))
+            throw new Error(usage);
+        await listen(credential, args[1] === "--resolve");
         return;
     }
     throw new Error(usage);
@@ -76,35 +136,72 @@ async function pairDevice(server) {
     }
     throw new Error("Pairing expired. Run the pairing command again for a new link.");
 }
-async function listen(credential) {
+async function listen(credential, resolve = false) {
+    const metadataAbort = new AbortController();
+    const names = createNameResolver((operation, cursor) => request(credential.server, `/v1/events/slack/${operation}?${new URLSearchParams({ limit: "200", cursor })}`, { token: credential.token, signal: metadataAbort.signal }));
+    const threadRoot = createThreadResolver((channel, ts) => request(credential.server, `/v1/events/slack/message?${new URLSearchParams({ id: channel, ts })}`, { token: credential.token, timeoutMs: 2_000, signal: metadataAbort.signal }));
     let after;
-    for (;;) {
-        const path = `/v1/events?wait_ms=30000${after === undefined ? "" : `&after=${after}`}`;
-        const response = await request(credential.server, path, { token: credential.token });
-        const events = Array.isArray(response.events) ? response.events : [];
-        for (const event of events)
-            await writeStdout(`${JSON.stringify(event)}\n`);
-        if (events.length > 0) {
-            const cursor = events.at(-1).sequence;
-            if (!Number.isSafeInteger(cursor))
-                throw new Error("Event feed returned an invalid cursor");
-            // This is only an in-process read position. The recipient explicitly
-            // ACKs after its own durable commit; stdout never advances that checkpoint.
-            after = cursor;
+    try {
+        for (;;) {
+            if (resolve)
+                void names.refresh();
+            const path = `/v1/events?wait_ms=30000${after === undefined ? "" : `&after=${after}`}`;
+            const response = await request(credential.server, path, { token: credential.token });
+            const events = Array.isArray(response.events) ? response.events : [];
+            for (const event of events) {
+                if (!resolve) {
+                    await writeStdout(`${JSON.stringify(event)}\n`);
+                    continue;
+                }
+                const enriched = names.enrich(requireObject(event));
+                const root = await threadRoot(requireObject(event));
+                if (root) {
+                    const rootNames = names.enrich({ event: root }).context.users;
+                    const bot = requireObject(root.bot_profile ?? {});
+                    enriched.context.threadRoot = { ts: root.ts, user: root.user, text: root.text,
+                        author: typeof root.user === "string" ? rootNames[root.user] ?? bot.name : bot.name };
+                }
+                const payload = requireObject(enriched.event ?? {});
+                if (payload.type === "file_shared") {
+                    try {
+                        const file = requireObject(payload.file ?? {});
+                        const id = requireString(payload.file_id ?? file.id, "file ID");
+                        const result = await request(credential.server, `/v1/events/slack/file?${new URLSearchParams({ id })}`, { token: credential.token, timeoutMs: 2_000 });
+                        enriched.context.files.push(requireObject(result.file));
+                    }
+                    catch (error) {
+                        process.stderr.write(`File lookup unavailable: ${error instanceof Error ? error.message : "request failed"}\n`);
+                    }
+                }
+                await writeStdout(`${JSON.stringify(enriched)}\n`);
+            }
+            if (events.length > 0) {
+                const cursor = events.at(-1).sequence;
+                if (!Number.isSafeInteger(cursor))
+                    throw new Error("Event feed returned an invalid cursor");
+                // This is only an in-process read position. The recipient explicitly
+                // ACKs after its own durable commit; stdout never advances that checkpoint.
+                after = cursor;
+            }
         }
     }
+    finally {
+        metadataAbort.abort();
+    }
 }
 async function request(server, path, options = {}) {
+    const timeout = AbortSignal.timeout(options.timeoutMs ?? 40_000);
     const response = await fetch(new URL(path, `${normalizeServer(server)}/`), {
-        signal: AbortSignal.timeout(40_000),
+        signal: options.signal ? AbortSignal.any([options.signal, timeout]) : timeout,
         method: options.method || "GET",
+        redirect: "error",
         headers: {
             ...(options.token ? { authorization: `Bearer ${options.token}` } : {}),
             ...(options.body ? { "content-type": "application/json" } : {}),
         },
         body: options.body ? JSON.stringify(options.body) : undefined,
     });
-    const body = await response.json();
+    const body = requireObject(await response.json());
     if (!response.ok)
         throw new Error(typeof body.error === "string" ? body.error : `Event server returned ${response.status}`);
     return body;
@@ -181,3 +278,131 @@ function writeStdout(text) {
         }
     });
 }
+/** A whole-directory snapshot belongs to one listener and its credential. */
+export function createNameResolver(fetchPage) {
+    let users = new Map();
+    let channels = new Map();
+    let refreshing;
+    let nextRefresh = 0;
+    async function readPages(operation, accept) {
+        let cursor = "";
+        const seen = new Set();
+        do {
+            seen.add(cursor);
+            const page = await fetchPage(operation, cursor);
+            const entries = page[operation === "users" ? "members" : "channels"];
+            if (!Array.isArray(entries))
+                throw new Error(`Invalid Slack ${operation} list`);
+            for (const entry of entries)
+                accept(requireObject(entry));
+            const metadata = requireObject(page.response_metadata ?? {});
+            cursor = metadata.next_cursor === undefined ? "" : requireCursor(metadata.next_cursor);
+            if (cursor && seen.has(cursor))
+                throw new Error("Slack directory repeated a pagination cursor");
+        } while (cursor);
+    }
+    async function refresh() {
+        try {
+            const nextUsers = new Map();
+            const nextChannels = new Map();
+            await readPages("users", user => {
+                const profile = requireObject(user.profile ?? {});
+                const name = profile.display_name || user.real_name || user.name;
+                if (typeof name === "string" && name)
+                    nextUsers.set(requireString(user.id, "user ID"), name);
+            });
+            await readPages("channels", channel => {
+                const id = requireString(channel.id, "channel ID");
+                const user = channel.is_im && typeof channel.user === "string" ? channel.user : undefined;
+                const name = user && nextUsers.has(user) ? `DM with ${nextUsers.get(user)}` : channel.name;
+                if (typeof name === "string" && name)
+                    nextChannels.set(id, { name, user });
+            });
+            // Publish only a complete snapshot; failed refreshes retain the previous one.
+            users = nextUsers;
+            channels = nextChannels;
+        }
+        catch (error) {
+            process.stderr.write(`Name refresh unavailable: ${error instanceof Error ? error.message : "request failed"}\n`);
+        }
+    }
+    return {
+        refresh() {
+            if (refreshing)
+                return refreshing;
+            if (Date.now() < nextRefresh)
+                return Promise.resolve();
+            nextRefresh = Date.now() + 6 * 60 * 60_000;
+            refreshing = refresh().finally(() => { refreshing = undefined; });
+            return refreshing;
+        },
+        enrich(delivery) {
+            const event = requireObject(delivery.event ?? {});
+            const message = requireObject(event.message ?? event.previous_message ?? event);
+            const item = requireObject(event.item ?? {});
+            const channelId = event.channel ?? item.channel ?? event.channel_id;
+            const channel = typeof channelId === "string" ? channels.get(channelId) : undefined;
+            const context = { users: {}, channels: {}, files: [] };
+            if (channel && typeof channelId === "string")
+                context.channels[channelId] = channel.name;
+            const ids = new Set([event.user, message.user, event.item_user, channel?.user,
+                ...Array.from(String(message.text ?? "").matchAll(/<@([A-Z0-9]+)(?:\|[^>]*)?>/g), match => match[1])]);
+            for (const id of ids) {
+                if (typeof id !== "string")
+                    continue;
+                const name = users.get(id);
+                if (name)
+                    context.users[id] = name;
+            }
+            return { ...delivery, context };
+        },
+    };
+}
+function requireObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Expected a JSON object");
+    return value;
+}
+function requireCursor(value) {
+    if (typeof value !== "string")
+        throw new Error("Invalid pagination cursor");
+    return value;
+}
+/** Cache thread roots per listener; a failed lookup must not prevent delivery. */
+export function createThreadResolver(fetchRoot) {
+    const cache = new Map();
+    const put = (key, root) => {
+        if (cache.size >= 1000)
+            cache.delete(cache.keys().next().value);
+        cache.set(key, { until: Date.now() + (root ? 3600_000 : 60_000), root });
+    };
+    return async (delivery) => {
+        const event = requireObject(delivery.event ?? {});
+        if (event.type !== "message" || typeof event.channel !== "string")
+            return undefined;
+        const message = requireObject(event.message ?? event.previous_message ?? event);
+        const ts = event.deleted_ts ?? message.ts;
+        const rootTs = message.thread_ts;
+        if (typeof rootTs !== "string" || rootTs === ts) {
+            if (typeof ts === "string")
+                put(`${event.channel}/${ts}`, event.subtype === "message_deleted" ? undefined : message);
+            return undefined;
+        }
+        const key = `${event.channel}/${rootTs}`;
+        const cached = cache.get(key);
+        if (cached && cached.until > Date.now())
+            return cached.root;
+        try {
+            const response = await fetchRoot(event.channel, rootTs);
+            const root = requireObject(response.message);
+            if (root.ts !== rootTs)
+                throw new Error("Thread root timestamp mismatch");
+            put(key, root);
+            return root;
+        }
+        catch {
+            put(key);
+            return undefined;
+        }
+    };
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@zksecurity/slack-events",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Pair a terminal with a pi-mom Slack event feed",
   "type": "module",
   "bin": { "slack-events": "bin/slack-events.mjs" },
-  "files": ["bin", "dist"],
+  "files": ["bin", "dist", "skills"],
   "engines": { "node": ">=24" },
   "license": "MIT",
   "repository": {

package/skills/slack-events/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: slack-events
+description: Read personal Slack events, resolve Slack user/channel IDs, inspect message or thread context, and retrieve shared files with the paired slack-events CLI.
+---
+
+# Personal Slack events
+
+Use `slack-events` on the paired machine. Run `slack-events --help` to inspect
+installed commands. The CLI uses its saved feed credential; the server makes
+read-only Slack calls under that subscriber's user OAuth grant. It cannot send
+messages or modify Slack. Commands requiring added scopes need server deployment
+and user reauthorization before they work.
+
+## Reading incoming events
+
+`listen` emits JSONL with `sequence`, stable `eventId`, `teamId`, `eventType`,
+`eventTime`, `receivedAt`, and the inner Slack `event`. `listen --resolve` adds
+`context.users`, `context.channels`, and file metadata for `file_shared` events.
+For replies, optional `context.threadRoot` supplies the root timestamp, user,
+author name, and text. Root lookups have a two-second deadline and are cached;
+a missing or inaccessible root leaves that field absent.
+The listener fetches a complete user and
+conversation name snapshot in the background at startup and every six hours,
+keeping the whole snapshot in memory between refreshes. Failed refreshes retain
+the last good snapshot. Names are resolved locally; unknown IDs remain IDs and
+never hold up event delivery. IDs remain in the CLI JSON. Restarting the listener fetches a fresh snapshot.
+Standalone file metadata is fetched separately with a two-second deadline;
+failure leaves the original event intact and `context.files` empty.
+
+A message can include `files` (uploaded files) and `attachments` (structured
+attachments or link previews). A `message_changed` event contains the current
+`message` and often `previous_message`; a deletion may include `previous_message`.
+A `file_shared` event may contain only `file_id` and `channel_id`: use `file` or
+`download` below. A file-only message can have empty text.
+
+Reactions use `reaction_added` / `reaction_removed`: `user` is the actor,
+`reaction` is the emoji name (including custom emoji), and `item` identifies the
+message or file. The event timestamp is not the target message timestamp.
+
+Event-time snapshots can differ from the current Slack content returned by read
+commands. The CLI emits the original event, not a rendered message or summary.
+
+## Context and names
+
+Use `users` and `channels` to discover IDs by inspecting their names before making
+individual reads. Results are in `members` and `channels` respectively. Directory
+commands take no ID and return one page; follow `response_metadata.next_cursor`
+with `--cursor` until empty. `list` lists feed subscriptions, not conversations.
+
+There is no separate thread ID: a thread is identified by its channel ID and root
+message timestamp. Use `history CHANNEL_ID` to find a root message's `ts`, then
+pass that timestamp to `thread`. For a reply, use its `thread_ts` instead.
+
+```sh
+slack-events users
+slack-events channels
+slack-events users --limit 200 --cursor NEXT_CURSOR
+slack-events user U012345
+slack-events channel C012345
+slack-events message C012345 1788884385.665039
+slack-events thread C012345 1788881468.871969 --limit 50
+slack-events history C012345 --limit 50
+slack-events history C012345 --limit 50 --cursor NEXT_CURSOR
+```
+
+Keep timestamps as strings with every decimal digit. `message` uses
+`reactions.get` to return the target message and reactions; its `message.thread_ts`
+identifies the parent if it is a reply. Use that timestamp with `thread` for
+surrounding context. If a reaction only supplies the target timestamp, inspect
+`message` before assuming the target is a thread root.
+
+A Slack message permalink encodes the channel and message timestamp for CLI
+lookup (`p1788884385665039` corresponds to `1788884385.665039`).
+
+Read commands print Slack JSON. For `users`, `channels`, `history`, and `thread`, follow
+`response_metadata.next_cursor` with `--cursor`; one page is not necessarily the
+complete history. `users:read` enables user lookups. Channel metadata requires
+the appropriate `*:read` scope. History uses the existing `*:history` scopes.
+
+## Files
+
+```sh
+slack-events file F012345
+slack-events download F012345 ./attachment.pdf
+```
+
+`file` returns metadata such as filename/title, MIME type, size, and Slack links.
+`download` streams the bytes to the explicit output path and refuses to overwrite
+an existing file. These commands require `files:read`. Files removed from Slack,
+external files without a downloadable URL, or files no longer accessible to the
+subscriber may not be downloadable. A private Slack URL is not a public link;
+use the authenticated CLI download rather than unauthenticated curl.
+
+## Feed lifecycle
+
+```sh
+slack-events pair https://YOUR-EVENT-HOST
+slack-events listen --resolve
+slack-events list
+```
+
+Pairing opens a browser authorization flow and stores the credential on the
+originating machine. Re-pair after new user scopes are granted. The credential
+lives at `$XDG_CONFIG_HOME/slack-events/credentials.json`, defaulting to
+`~/.config/slack-events/credentials.json`; do not print it.
+
+Reading or printing does not acknowledge. A durable consumer deduplicates by
+`eventId`, commits all deliveries through a sequence, then calls
+`slack-events ack SEQUENCE`. Never ACK a cursor just to inspect events. Only one
+acknowledging consumer should use a paired credential; unacknowledged events
+replay on restart subject to server retention. `revoke SUBSCRIPTION_ID` disables
+a subscription; use it only when asked to revoke access.