@zksecurity/slack-events 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# Slack Events Client
+
+Requires Node.js 24 or newer. Run on the machine that will consume your events:
+
+```sh
+npx @zksecurity/slack-events pair https://YOUR-EVENT-HOST
+```
+
+Leave the command running and open its printed link in your laptop's browser
+(or any browser with your Slack login). Confirm the matching terminal code and
+authorize Slack. The waiting command saves the feed credential on the originating
+machine, prints `Paired with ...`, and exits. No inbound port, SSH forwarding,
+or copying a credential back is needed.
+
+Pairing does not start a listener. On the same machine, run:
+
+```sh
+npx @zksecurity/slack-events listen
+```
+
+`listen` stays running and prints one JSON object per event from your personal
+feed, including available backlog and new arrivals. It uses the saved credential;
+no URL or browser login is needed. Stop with Ctrl+C and run `listen` again later
+without repeating pairing.
+
+Printing events does not acknowledge them. For durable consumption, save all
+events through a `sequence` cursor before acknowledging it:
+
+```sh
+npx @zksecurity/slack-events ack COMMITTED_CURSOR
+```
+
+Unacknowledged events replay after restarting the listener, subject to server
+retention. Deduplicate by `eventId`; never ACK merely because an event reached
+stdout or a pipe.
+
+Other commands:
+
+```sh
+npx @zksecurity/slack-events list
+npx @zksecurity/slack-events revoke SUBSCRIPTION_ID
+```
+
+Credentials are stored with mode `0600` in
+`$XDG_CONFIG_HOME/pi-mom/slack-events.json` or `~/.config/pi-mom/slack-events.json`.
+
+For existing browser-issued pairing codes, `pair SERVER CODE` is also supported.
+
+## Maintainers
+
+From a pi-mom checkout with development dependencies installed:
+
+```sh
+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.

package/bin/slack-events.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runSlackEventsCli } from "../dist/cli.js";
+
+try {
+  await runSlackEventsCli(process.argv.slice(2));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/dist/cli.js

@@ -0,0 +1,183 @@
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } 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 command = args[0];
+    if (!command || command === "--help" || command === "-h") {
+        process.stdout.write(`${usage}\n`);
+        return;
+    }
+    if (command === "pair") {
+        const server = requireArgument(args[1], "server URL");
+        const code = args[2];
+        const token = code
+            ? requireString((await request(server, "/v1/events/pair", { method: "POST", body: { code } })).token, "pair response token")
+            : await pairDevice(server);
+        writeCredential({ server: normalizeServer(server), token });
+        process.stdout.write(`Paired with ${normalizeServer(server)}\n`);
+        return;
+    }
+    const credential = readCredential();
+    if (command === "ack") {
+        const value = requireArgument(args[1], "committed cursor");
+        const cursor = Number(value);
+        if (!/^\d+$/.test(value) || !Number.isSafeInteger(cursor))
+            throw new Error("Invalid committed cursor");
+        await request(credential.server, "/v1/events/ack", { method: "POST", token: credential.token, body: { cursor } });
+        return;
+    }
+    if (command === "list") {
+        const response = await request(credential.server, "/v1/events/subscriptions", { token: credential.token });
+        process.stdout.write(`${JSON.stringify(response.subscriptions, null, 2)}\n`);
+        return;
+    }
+    if (command === "revoke") {
+        const subscriptionId = requireArgument(args[1], "subscription id");
+        await request(credential.server, `/v1/events/subscriptions/${encodeURIComponent(subscriptionId)}`, {
+            method: "DELETE",
+            token: credential.token,
+        });
+        process.stdout.write(`Revoked ${subscriptionId}\n`);
+        return;
+    }
+    if (command === "listen") {
+        await listen(credential);
+        return;
+    }
+    throw new Error(usage);
+}
+async function pairDevice(server) {
+    const pairing = await request(server, "/v1/events/pair/start", { method: "POST" });
+    const deviceCode = requireString(pairing.device_code, "device code");
+    const verificationUrl = new URL(requireString(pairing.verification_uri, "verification URL"));
+    if (verificationUrl.origin !== new URL(normalizeServer(server)).origin)
+        throw new Error("Unexpected verification URL origin");
+    const userCode = requireString(pairing.user_code, "verification code");
+    const expiresIn = requirePositiveInteger(pairing.expires_in, "pairing expiry");
+    const interval = requirePositiveInteger(pairing.interval, "poll interval");
+    const deadline = Date.now() + expiresIn * 1000;
+    process.stdout.write(`Open this link in a browser where you are logged into Slack:\n${verificationUrl}\n\nConfirm code: ${userCode}\nWaiting for authorization...\n`);
+    while (Date.now() < deadline) {
+        await new Promise(resolve => setTimeout(resolve, Math.min(interval * 1000, deadline - Date.now())));
+        if (Date.now() >= deadline)
+            break;
+        const result = await request(server, "/v1/events/pair/poll", {
+            method: "POST", body: { device_code: deviceCode },
+        });
+        if (result.status === "approved")
+            return requireString(result.token, "pair response token");
+        if (result.status === "denied")
+            throw new Error("Authorization was denied. Run the pairing command again to retry.");
+        if (result.status === "expired")
+            break;
+        if (result.status !== "pending")
+            throw new Error("Invalid device pairing response");
+    }
+    throw new Error("Pairing expired. Run the pairing command again for a new link.");
+}
+async function listen(credential) {
+    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;
+        }
+    }
+}
+async function request(server, path, options = {}) {
+    const response = await fetch(new URL(path, `${normalizeServer(server)}/`), {
+        signal: AbortSignal.timeout(40_000),
+        method: options.method || "GET",
+        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();
+    if (!response.ok)
+        throw new Error(typeof body.error === "string" ? body.error : `Event server returned ${response.status}`);
+    return body;
+}
+function credentialPath() {
+    const configRoot = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+    return join(configRoot, "pi-mom", "slack-events.json");
+}
+function writeCredential(credential) {
+    const path = credentialPath();
+    const directory = dirname(path);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    chmodSync(directory, 0o700);
+    writeFileSync(path, `${JSON.stringify(credential, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+function readCredential() {
+    let parsed;
+    try {
+        const path = credentialPath();
+        chmodSync(dirname(path), 0o700);
+        chmodSync(path, 0o600);
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error("No Slack event feed credential. Run `slack-events pair <server>` first.");
+    }
+    if (!parsed || typeof parsed !== "object")
+        throw new Error("Invalid Slack event feed credential file");
+    const value = parsed;
+    return {
+        server: requireString(value.server, "credential server"),
+        token: requireString(value.token, "credential token"),
+    };
+}
+function normalizeServer(server) {
+    const url = new URL(server);
+    if (url.protocol !== "https:" && url.hostname !== "127.0.0.1" && url.hostname !== "localhost") {
+        throw new Error("Slack event server must use HTTPS except on localhost");
+    }
+    return url.toString().replace(/\/$/, "");
+}
+function requireArgument(value, name) {
+    if (!value)
+        throw new Error(`Missing ${name}`);
+    return value;
+}
+function requireString(value, name) {
+    if (typeof value !== "string" || !value)
+        throw new Error(`Invalid ${name}`);
+    return value;
+}
+function requirePositiveInteger(value, name) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > 3600) {
+        throw new Error(`Invalid ${name}`);
+    }
+    return value;
+}
+function writeStdout(text) {
+    return new Promise((resolve, reject) => {
+        if (process.stdout.write(text))
+            resolve();
+        else {
+            const onDrain = () => {
+                process.stdout.off("error", onError);
+                resolve();
+            };
+            const onError = (error) => {
+                process.stdout.off("drain", onDrain);
+                reject(error);
+            };
+            process.stdout.once("drain", onDrain);
+            process.stdout.once("error", onError);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@zksecurity/slack-events",
+  "version": "0.1.0",
+  "description": "Pair a terminal with a pi-mom Slack event feed",
+  "type": "module",
+  "bin": { "slack-events": "bin/slack-events.mjs" },
+  "files": ["bin", "dist"],
+  "engines": { "node": ">=24" },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zksecurity/pi-mom.git",
+    "directory": "packages/slack-events"
+  },
+  "publishConfig": { "access": "public" },
+  "scripts": { "prepack": "node ../../scripts/build-slack-events-client.mjs" }
+}