@jr2/orchestrator 0.5.1 → 0.7.0

package/src/hook-kinds/slack.ts

@@ -0,0 +1,151 @@
+// `@jr2/orchestrator/hooks/slack`: jr2's Slack kind. One Slack app at one address: its slash commands, its
+// interactivity (Block Kit clicks) and its Events API.
+
+import { z } from "zod";
+import { defineHookKind, form, json, type Delivery, type HookRequest } from "./index.ts";
+
+/**
+ * The schema of each event key. A key with `.*` covers a family: the command or the action id is
+ * part of the key, so one schema types `block_actions.approve` and `block_actions.reject`.
+ */
+export const slackEvents = {
+  /** A slash command, decoded from its form body: each field is a string. */
+  "slash_command.*": z.looseObject({ text: z.string(), user_id: z.string(), channel_id: z.string() }),
+  /** A Block Kit click, decoded from the JSON in its `payload` form field. */
+  "block_actions.*": z.looseObject({
+    user: z.looseObject({ id: z.string() }),
+    channel: z.looseObject({ id: z.string() }).optional(),
+    message: z.looseObject({ ts: z.string() }).optional(),
+    actions: z.array(z.looseObject({ action_id: z.string(), value: z.string().optional() })),
+    /** The kind's `answer` posts the text here. A click with no `response_url` fails the parse. */
+    response_url: z.string(),
+  }),
+  "event_callback.app_mention": z.looseObject({
+    event: z.looseObject({ user: z.string(), text: z.string(), channel: z.string(), ts: z.string() }),
+  }),
+};
+
+const text = (v: unknown): string | undefined => (typeof v === "string" && v !== "" ? v : undefined);
+
+const need = (v: string | undefined, what: string): string => {
+  if (v === undefined) throw new Error(`no ${what}`);
+  return v;
+};
+
+/** Slack's three characters that a `text` must escape. */
+const escape = (s: string): string => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+const isForm = (req: HookRequest): boolean =>
+  (req.headers["content-type"] ?? "").toLowerCase().startsWith("application/x-www-form-urlencoded");
+
+/** The host of a click's `response_url`. */
+const RESPONSE_HOST = "https://hooks.slack.com/";
+
+/**
+ * - verifier: `mac`, HMAC-SHA256 of `v0:<X-Slack-Request-Timestamp>:<raw body>`,
+ *   `X-Slack-Signature: v0=<hex>`. The signature covers the timestamp, so the kind gives it as
+ *   `at`, and the door's 300 s window applies (Slack asks for 5 minutes).
+ * - handshake: `url_verification` gets `{ challenge }`. The door verifies it first. (Slack's docs
+ *   do not say that Slack signs it; check it at the first real setup.)
+ * - body: a command is a form; a click is a form with JSON in `payload`; an event is JSON.
+ * - event keys: `slash_command./jr2`, `block_actions.<action_id>`, `event_callback.<event.type>`.
+ * - delivery id: `event_id` for an event, `trigger_id` for a command or a click. (Slack's docs do
+ *   not say that a `trigger_id` is unique for each request; the door's repeat check also uses the
+ *   digest of the body.)
+ * - `onBehalfOf`: the Slack user id, never a display name.
+ * - who reads the answer: a person for a command or a click; Slack for an event (so a 503 stays a
+ *   503, and Slack sends the event again).
+ * - answer: ephemeral text. The answer to a click can only be an empty 200 (Block Kit), so the text
+ *   goes to the click's `response_url` as the answer's `then`.
+ * - text limit: 4000 characters, the length that Slack's docs advise for a message's `text`. (Not
+ *   checked for the answer to a command or a `response_url` post.)
+ */
+export const slack = defineHookKind({
+  api: 1,
+  id: "slack",
+  events: slackEvents,
+  verify: {
+    mac: {
+      alg: "sha256",
+      signed: (req) => {
+        const ts = req.headers["x-slack-request-timestamp"];
+        const sig = req.headers["x-slack-signature"];
+        if (ts === undefined || !/^\d+$/.test(ts) || !sig?.startsWith("v0=")) {
+          return { unsigned: "no Slack signature or timestamp" };
+        }
+        return { bytes: ["v0:", ts, ":", req.body], signature: { hex: sig.slice("v0=".length) }, at: Number(ts) };
+      },
+    },
+  },
+  read: (req) => {
+    if (isForm(req)) {
+      const f = form(req);
+      if (f.payload !== undefined) {
+        let p: { readonly type?: unknown; readonly trigger_id?: unknown; readonly user?: { readonly id?: unknown } };
+        try {
+          p = JSON.parse(f.payload) as typeof p;
+        } catch {
+          throw new Error("the payload field is not JSON");
+        }
+        const type = need(text(p?.type), "payload type");
+        const action = text(
+          (p as { readonly actions?: readonly { readonly action_id?: unknown }[] }).actions?.[0]?.action_id,
+        );
+        const by = text(p.user?.id);
+        return {
+          key: action ? `${type}.${action}` : type,
+          id: need(text(p.trigger_id), "trigger_id"),
+          payload: p,
+          ...(by ? { onBehalfOf: by } : {}),
+          readBy: "person",
+        };
+      }
+      return {
+        key: `slash_command.${need(text(f.command), "command")}`,
+        id: need(text(f.trigger_id), "trigger_id"),
+        payload: f,
+        ...(text(f.user_id) ? { onBehalfOf: f.user_id } : {}),
+        readBy: "person",
+      };
+    }
+    const p = json(req) as {
+      readonly type?: unknown;
+      readonly challenge?: unknown;
+      readonly event_id?: unknown;
+      readonly event?: { readonly type?: unknown; readonly user?: unknown };
+    } | null;
+    const type = need(text(p?.type), "type");
+    if (type === "url_verification") return { handshake: { body: { challenge: text(p?.challenge) ?? "" } } };
+    const event = text(p?.event?.type);
+    const by = text(p?.event?.user);
+    return {
+      key: event ? `${type}.${event}` : type,
+      id: need(text(p?.event_id), "event_id"),
+      payload: p,
+      ...(by ? { onBehalfOf: by } : {}),
+    };
+  },
+  answer: (t: string, d: Delivery) => {
+    if (d.key.startsWith("block_actions.")) {
+      const url = text((d.payload as { readonly response_url?: unknown }).response_url);
+      // The door refuses a `then` outside `posts`; a url of another host gets no post at all.
+      if (url === undefined || !url.startsWith(RESPONSE_HOST)) return { body: null };
+      return {
+        body: null,
+        then: {
+          post: url as `https://${string}`,
+          json: { response_type: "ephemeral", replace_original: false, text: escape(t) },
+        },
+      };
+    }
+    return { body: { response_type: "ephemeral", text: escape(t) } };
+  },
+  maxText: 4000,
+  posts: [RESPONSE_HOST],
+});
+
+declare module "./index.ts" {
+  interface HookKinds {
+    slack: typeof slack;
+  }
+}

package/src/hook-kinds/webhook.ts

@@ -0,0 +1,113 @@
+// `@jr2/orchestrator/hooks/webhook`: the general kind, for a service that has no kind of its own (ADR-0078). It
+// makes a kind from data, through `defineHookKind`, as each other kind is made. So it gives a kind
+// nothing that the interface does not give a kind from another package.
+//
+// It makes a kind, not a Hook: the service's protocol is the same for each Instance, so the
+// Instance writes it one time, in a module of its own that `jr2.config.ts` imports for its Hooks
+// and the Workflows import for their handlers. The Hook in the config gives only the credential
+// and `may`.
+//
+// What it cannot do: a handshake, a body that is not JSON, a signature over more than the raw
+// body, a signed timestamp, and an answer that a person reads. A service that needs one of them
+// needs a kind module.
+
+import {
+  at,
+  defineHookKind,
+  json,
+  type Events,
+  type HookKindOf,
+  type HookRequest,
+  type MacAlg,
+  type Verify,
+} from "./index.ts";
+
+/** Where a value is in a delivery: a header (lowercase), or a dotted path in the JSON body. */
+export type Field = { readonly header: string } | { readonly json: string };
+
+/** How the general kind verifies. `mac` is over the raw body only. */
+export type WebhookVerify =
+  | {
+      readonly mac: {
+        /** The header of the signature (lowercase). */
+        readonly header: string;
+        /** `sha256` when it is not given. */
+        readonly alg?: MacAlg;
+        /** The text before the signature in the header's value, such as `sha256=`. */
+        readonly prefix?: string;
+        /** `hex` when it is not given. */
+        readonly encoding?: "hex" | "base64";
+      };
+    }
+  | { readonly token: { readonly header: string } };
+
+type VerifyOf<W extends WebhookVerify> = W extends { readonly mac: unknown }
+  ? Extract<Verify, { readonly mac: unknown }>
+  : Extract<Verify, { readonly token: unknown }>;
+
+/** The text of a field's value: a string, or a number as a string. */
+function pick(req: HookRequest, body: unknown, f: Field): string | undefined {
+  const v = "header" in f ? req.headers[f.header.toLowerCase()] : at(body, f.json);
+  if (typeof v === "number" && Number.isFinite(v)) return String(v);
+  return typeof v === "string" && v !== "" ? v : undefined;
+}
+
+/**
+ * A kind from data.
+ * - `id`: the kind's id. The Instance chooses it; it must not be the id of another kind.
+ * - `events`: a zod schema for each event key that a handler can hear. The door parses with it, as
+ *   for each kind (`Events` in `@jr2/orchestrator/hooks`).
+ * - `verify`: `mac` over the raw body (the header, its prefix, the algorithm, the encoding), or
+ *   `token` in a header.
+ * - `key`: the event key, from one field; or `{ name, action }`, which gives `<name>.<action>`, or
+ *   `<name>` when the delivery has no action.
+ * - `delivery`: the delivery id. `onBehalfOf`: optional.
+ *
+ * The answer is the outcome JSON.
+ */
+export function webhook<const Id extends string, const E extends Events, const W extends WebhookVerify>(spec: {
+  readonly id: Id;
+  readonly events: E;
+  readonly verify: W;
+  readonly key: Field | { readonly name: Field; readonly action?: Field };
+  readonly delivery: Field;
+  readonly onBehalfOf?: Field;
+}): HookKindOf<Id, E, VerifyOf<W>> {
+  const sv = spec.verify as WebhookVerify;
+  let verify: Verify;
+  if ("mac" in sv) {
+    const mac = sv.mac;
+    const header = mac.header.toLowerCase();
+    const prefix = mac.prefix ?? "";
+    verify = {
+      mac: {
+        alg: mac.alg ?? "sha256",
+        signed: (req) => {
+          const raw = req.headers[header];
+          if (raw === undefined || !raw.startsWith(prefix)) return { unsigned: `no ${header} header` };
+          const value = raw.slice(prefix.length);
+          return { bytes: [req.body], signature: mac.encoding === "base64" ? { base64: value } : { hex: value } };
+        },
+      },
+    };
+  } else {
+    verify = { token: { header: sv.token.header.toLowerCase() } };
+  }
+  const k = spec.key;
+  return defineHookKind({
+    api: 1,
+    id: spec.id,
+    events: spec.events,
+    verify,
+    read: (req) => {
+      const body = json(req);
+      const name = "name" in k ? pick(req, body, k.name) : pick(req, body, k);
+      const action = "name" in k && k.action ? pick(req, body, k.action) : undefined;
+      const id = pick(req, body, spec.delivery);
+      if (name === undefined) throw new Error("the delivery has no event name");
+      if (id === undefined) throw new Error("the delivery has no delivery id");
+      const by = spec.onBehalfOf ? pick(req, body, spec.onBehalfOf) : undefined;
+      return { key: action ? `${name}.${action}` : name, id, payload: body, ...(by ? { onBehalfOf: by } : {}) };
+    },
+  }) as unknown as HookKindOf<Id, E, VerifyOf<W>>;
+}