hono-webhooks 0.1.0 → 0.2.0

package/dist/cli.js

@@ -1,35 +1,421 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
+
+// src/index.ts
+import { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { basePath } from "hono/route";
+
+class WebhookValidationError extends HTTPException {
+  target;
+  issues;
+  constructor(target, issues) {
+    super(target === "signature" ? 401 : 400, {
+      message: `Invalid ${target}`
+    });
+    this.target = target;
+    this.issues = issues;
+    this.name = "WebhookValidationError";
+  }
+}
+function makeDefineWebhook() {
+  return (config, handler) => ({
+    config,
+    handler
+  });
+}
+function detectBodyType(contentType = "") {
+  if (/[/+]json\b/i.test(contentType))
+    return "json";
+  if (/x-www-form-urlencoded/i.test(contentType))
+    return "form";
+  return "text";
+}
+function parseBody(raw, type, contentType) {
+  if (!raw)
+    return;
+  const resolved = type === "auto" ? detectBodyType(contentType) : type;
+  if (resolved === "text")
+    return raw;
+  if (resolved === "form")
+    return Object.fromEntries(new URLSearchParams(raw));
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new WebhookValidationError("body", [{ message: "Malformed JSON" }]);
+  }
+}
+async function parse(schema, value, target) {
+  if (!schema)
+    return value;
+  const result = await schema["~standard"].validate(value);
+  if (result.issues)
+    throw new WebhookValidationError(target, result.issues);
+  return result.value;
+}
+function defaultErrorResponse(error, c, log) {
+  if (error instanceof WebhookValidationError) {
+    return c.json({ error: error.message, issues: error.issues }, error.status);
+  }
+  if (error instanceof HTTPException) {
+    return error.res ?? c.json({ error: error.message }, error.status);
+  }
+  if (log)
+    console.error(error);
+  return c.json({ error: "Internal Server Error" }, 500);
+}
+function report(c, pending) {
+  if (!(pending instanceof Promise))
+    return;
+  const handled = pending.catch((error) => console.error("hono-webhooks: onEvent failed", error));
+  try {
+    c.executionCtx.waitUntil(handled);
+  } catch {}
+}
+function isDynamic(path) {
+  return path.includes(":") || path.includes("*");
+}
+function makeCreateWebhooks() {
+  return (webhooks, options = {}) => {
+    const app = new Hono;
+    const methodsByPath = new Map;
+    for (const { config } of webhooks) {
+      const methods = methodsByPath.get(config.path) ?? [];
+      if (methods.includes(config.method)) {
+        throw new Error(`hono-webhooks: ${config.method} ${config.path} is defined twice`);
+      }
+      methods.push(config.method);
+      methodsByPath.set(config.path, methods);
+    }
+    const handle = (route, run) => {
+      const execute = async (c) => {
+        const start = performance.now();
+        const base = basePath(c);
+        const event = {
+          c,
+          route,
+          method: c.req.method,
+          path: base === "/" ? c.req.path : c.req.path.slice(base.length) || "/",
+          status: 0,
+          durationMs: 0
+        };
+        let res;
+        try {
+          res = await run(c, event);
+        } catch (error) {
+          event.error = error;
+          if (error instanceof WebhookValidationError) {
+            event.validation = { target: error.target, issues: error.issues };
+          }
+          res = await options.onError?.(error, c) ?? defaultErrorResponse(error, c, options.logErrors ?? true);
+        }
+        event.status = res.status;
+        event.durationMs = performance.now() - start;
+        if (options.onEvent)
+          report(c, options.onEvent(event));
+        return res;
+      };
+      const { around } = options;
+      return (c) => around ? around({ c, route, method: c.req.method }, () => execute(c)) : execute(c);
+    };
+    const ordered = [...webhooks].sort((a, b) => Number(isDynamic(a.config.path)) - Number(isDynamic(b.config.path)));
+    for (const { config, handler } of ordered) {
+      app.on(config.method, config.path, handle(config.path, async (c, event) => {
+        event.params = await parse(config.params, c.req.param(), "params");
+        event.query = await parse(config.query, c.req.query(), "query");
+        event.headers = await parse(config.headers, c.req.header(), "headers");
+        event.rawBody = await c.req.text();
+        if (config.verify && !await config.verify({
+          c,
+          rawBody: event.rawBody,
+          headers: c.req.header()
+        })) {
+          throw new WebhookValidationError("signature", [
+            { message: "Signature does not match" }
+          ]);
+        }
+        event.body = await parse(config.body, parseBody(event.rawBody, config.bodyType ?? "auto", c.req.header("content-type")), "body");
+        const result = await handler({
+          c,
+          params: event.params,
+          query: event.query,
+          headers: event.headers,
+          body: event.body,
+          rawBody: event.rawBody
+        });
+        if (result instanceof Response)
+          return result;
+        event.response = result;
+        if (config.response) {
+          const checked = await config.response["~standard"].validate(result);
+          if (checked.issues) {
+            event.validation = { target: "response", issues: checked.issues };
+          }
+        }
+        if (result === undefined)
+          return c.body(null, 204);
+        if (typeof result === "string") {
+          return c.text(result, 200, {
+            "content-type": "text/plain; charset=UTF-8"
+          });
+        }
+        return c.json(result);
+      }));
+    }
+    for (const [path, methods] of methodsByPath) {
+      app.all(path, handle(path, async (c) => {
+        c.header("Allow", methods.join(", "));
+        throw new HTTPException(405, {
+          message: `Method ${c.req.method} not allowed`
+        });
+      }));
+    }
+    app.all("*", handle(undefined, async () => {
+      throw new HTTPException(404, { message: "Route not found" });
+    }));
+    return Object.assign(app, { webhooks });
+  };
+}
+var defineWebhook = makeDefineWebhook();
+var createWebhooks = makeCreateWebhooks();
+function createWebhookFactory() {
+  return {
+    defineWebhook: makeDefineWebhook(),
+    createWebhooks: makeCreateWebhooks()
+  };
+}
+function formatIssues(issues) {
+  return issues.map((issue) => {
+    const path = issuePath(issue);
+    return path ? `${path}: ${issue.message}` : issue.message;
+  }).join("; ");
+}
+function issuePath(issue) {
+  const path = issue.path?.map((segment) => String(typeof segment === "object" ? segment.key : segment)).join(".");
+  return path || null;
+}
+function summarizeEvent(event) {
+  const { c, error, validation } = event;
+  return {
+    route: event.route ?? null,
+    method: event.method,
+    path: event.path,
+    status: event.status,
+    durationMs: Math.round(event.durationMs * 100) / 100,
+    ip: c.req.header("x-forwarded-for")?.split(",")[0]?.trim() || c.req.header("x-real-ip") || c.req.header("cf-connecting-ip") || null,
+    userAgent: c.req.header("user-agent") ?? null,
+    params: event.params ?? null,
+    query: event.query ?? null,
+    body: event.body ?? null,
+    response: event.response ?? null,
+    error: error === undefined ? null : error instanceof Error ? {
+      name: error.name,
+      message: error.message,
+      stack: error.stack ?? null
+    } : { name: "Error", message: String(error), stack: null },
+    validation: validation ? {
+      target: validation.target,
+      message: formatIssues(validation.issues),
+      issues: validation.issues.map((issue) => ({
+        message: issue.message,
+        path: issuePath(issue)
+      }))
+    } : null
+  };
+}
+function toJsonSchema(schema, side, target) {
+  const props = schema?.["~standard"];
+  try {
+    return props?.jsonSchema?.[side]({ target }) ?? null;
+  } catch {
+    return null;
+  }
+}
+function describeWebhooks(source, { target = "draft-2020-12" } = {}) {
+  const webhooks = "webhooks" in source ? source.webhooks : source;
+  return webhooks.map(({ config }) => ({
+    method: config.method,
+    path: config.path,
+    description: config.description ?? null,
+    verified: Boolean(config.verify),
+    bodyType: config.bodyType ?? "auto",
+    jsonSchema: {
+      params: toJsonSchema(config.params, "input", target),
+      query: toJsonSchema(config.query, "input", target),
+      headers: toJsonSchema(config.headers, "input", target),
+      body: toJsonSchema(config.body, "input", target),
+      response: toJsonSchema(config.response, "output", target)
+    }
+  }));
+}
+function fillPath(pattern, params) {
+  return pattern.replace(/\/:(\w+)(?:\{[^}]*\})?\??/g, (_, name) => {
+    const value = params[name];
+    return value === undefined ? "" : `/${encodeURIComponent(String(value))}`;
+  });
+}
+async function testWebhook(webhook, input = {}) {
+  const { config } = webhook;
+  const { body, sign, env, options } = input;
+  const headers = new Headers(input.headers);
+  let rawBody;
+  if (typeof body === "string") {
+    rawBody = body;
+    if (!headers.has("content-type"))
+      headers.set("content-type", "text/plain");
+  } else if (body !== undefined && config.bodyType === "form") {
+    rawBody = new URLSearchParams(body).toString();
+    if (!headers.has("content-type")) {
+      headers.set("content-type", "application/x-www-form-urlencoded");
+    }
+  } else if (body !== undefined) {
+    rawBody = JSON.stringify(body);
+    if (!headers.has("content-type")) {
+      headers.set("content-type", "application/json");
+    }
+  }
+  for (const [name, value] of Object.entries(await sign?.(rawBody ?? "") ?? {})) {
+    headers.set(name, value);
+  }
+  const path = input.path ?? fillPath(config.path, input.params ?? {});
+  const query = new URLSearchParams(input.query).toString();
+  return createWebhooks([webhook], options).request(`${path || "/"}${query ? `?${query}` : ""}`, { method: config.method, headers, body: rawBody }, env);
+}
+
+// src/signatures.ts
+var encoder = new TextEncoder;
+function hmacKey(secret, hash) {
+  if (!secret)
+    throw new Error("hono-webhooks: the signing secret is empty");
+  return crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash }, false, ["sign", "verify"]);
+}
+async function hmacSign(secret, payload, hash = "SHA-256") {
+  const key = await hmacKey(secret, hash);
+  return new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(payload)));
+}
+async function hmacVerify(secret, payload, signature, hash = "SHA-256") {
+  const key = await hmacKey(secret, hash);
+  return crypto.subtle.verify("HMAC", key, signature, encoder.encode(payload));
+}
+var toHex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+var toBase64 = (bytes) => btoa(String.fromCharCode(...bytes));
+function fromHex(hex) {
+  if (hex.length % 2 || /[^0-9a-f]/i.test(hex))
+    return;
+  return Uint8Array.from(hex.match(/../g) ?? [], (h) => Number.parseInt(h, 16));
+}
+function fromBase64(base64) {
+  try {
+    return Uint8Array.from(atob(base64), (ch) => ch.charCodeAt(0));
+  } catch {
+    return;
+  }
+}
+var resolveSecret = async (secret, c) => typeof secret === "function" ? secret(c) : secret;
+function hmac(options) {
+  const { header, encoding, prefix = "", hash = "SHA-256" } = options;
+  const name = header.toLowerCase();
+  return {
+    verify: (secret) => async ({ c, rawBody, headers }) => {
+      const value = headers[name];
+      if (!value?.startsWith(prefix))
+        return false;
+      const encoded = value.slice(prefix.length);
+      const signature = encoding === "hex" ? fromHex(encoded) : fromBase64(encoded);
+      if (!signature)
+        return false;
+      return hmacVerify(await resolveSecret(secret, c), rawBody, signature, hash);
+    },
+    async sign(rawBody, secret) {
+      const signature = await hmacSign(secret, rawBody, hash);
+      return {
+        [name]: `${prefix}${encoding === "hex" ? toHex(signature) : toBase64(signature)}`
+      };
+    }
+  };
+}
+var github = hmac({
+  header: "x-hub-signature-256",
+  encoding: "hex",
+  prefix: "sha256="
+});
+var shopify = hmac({
+  header: "x-shopify-hmac-sha256",
+  encoding: "base64"
+});
+var stripe = {
+  verify: (secret, { toleranceSeconds = 300 } = {}) => async ({ c, rawBody, headers }) => {
+    const parts = (headers["stripe-signature"] ?? "").split(",").map((part) => part.split("="));
+    const timestamp = parts.find(([k]) => k === "t")?.[1] ?? "";
+    if (!/^\d+$/.test(timestamp))
+      return false;
+    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) {
+      return false;
+    }
+    const key = await resolveSecret(secret, c);
+    for (const [k, v] of parts) {
+      const signature = k === "v1" && v ? fromHex(v) : undefined;
+      if (signature && await hmacVerify(key, `${timestamp}.${rawBody}`, signature)) {
+        return true;
+      }
+    }
+    return false;
+  },
+  async sign(rawBody, secret, { timestamp } = {}) {
+    const t = timestamp ?? Math.floor(Date.now() / 1000);
+    const signature = await hmacSign(secret, `${t}.${rawBody}`);
+    return { "stripe-signature": `t=${t},v1=${toHex(signature)}` };
+  }
+};
+
+// src/cli.ts
+var schemes = {
+  github,
+  shopify,
+  stripe
+};
 var HELP = `Usage: hono-webhooks <module> <command> [options]
 
-<module> exports the result of createWebhooks(), as default or named export.
+<module> exports a createWebhooks() app or an array of webhooks, as default
+or named export.
 
 Commands:
   list                      List the webhooks
   schema <path>             Print the JSON Schemas of the webhooks at <path>
   test <method> <path>      Send a request through the webhooks app
 
+Options:
+  -r, --preload <module>    Import a module first (e.g. to load secrets), repeatable
+
 Options for test:
   -b, --body <text>         Request body (JSON sets content-type: application/json)
   -q, --query <params>      Query string, e.g. "a=1&b=2"
   -H, --header <k: v>       Request header, repeatable
+  -s, --sign <scheme>       Sign the body: ${Object.keys(schemes).join(", ")}
+  -e, --secret-env <name>   Environment variable holding the signing secret
 
 Examples:
   hono-webhooks ./src/webhooks.ts list
   hono-webhooks ./src/webhooks.ts schema /orders/:id
   hono-webhooks ./src/webhooks.ts test POST /orders/42 -b '{"total":10}'
+  hono-webhooks ./src/webhooks.ts test POST /shopify -b '{"id":1}' \\
+    -r ./src/secrets.ts --sign shopify --secret-env SHOPIFY_WEBHOOK_SECRET
 `;
 var { values, positionals } = parseArgs({
   allowPositionals: true,
   options: {
     help: { type: "boolean", short: "h" },
+    preload: { type: "string", short: "r", multiple: true },
     body: { type: "string", short: "b" },
     query: { type: "string", short: "q" },
-    header: { type: "string", short: "H", multiple: true }
+    header: { type: "string", short: "H", multiple: true },
+    sign: { type: "string", short: "s" },
+    "secret-env": { type: "string", short: "e" }
   }
 });
 var [modulePath, command, ...args] = positionals;
@@ -37,31 +423,46 @@ function fail(message) {
   console.error(message);
   process.exit(1);
 }
+var importModule = (specifier) => existsSync(resolve(specifier)) ? import(pathToFileURL(resolve(specifier)).href) : import(specifier);
 function isWebhooksApp(value) {
   return typeof value === "object" && value !== null && Array.isArray(value.webhooks) && typeof value.request === "function";
 }
+function isWebhookArray(value) {
+  return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item?.config?.path === "string" && typeof item?.handler === "function");
+}
 async function loadApp(path) {
-  const mod = await import(pathToFileURL(resolve(path)).href);
-  const app = [mod.default, ...Object.values(mod)].find(isWebhooksApp);
-  return app ?? fail(`${path} does not export a createWebhooks() app`);
+  const mod = await importModule(path);
+  const candidates = [mod.default, ...Object.values(mod)];
+  const app = candidates.find(isWebhooksApp);
+  if (app)
+    return app;
+  const webhooks = candidates.find(isWebhookArray);
+  if (webhooks)
+    return createWebhooks(webhooks);
+  return fail(`${path} exports neither a createWebhooks() app nor an array of webhooks`);
 }
-function jsonSchemaOf(schema) {
-  const props = schema["~standard"];
-  try {
-    return props?.jsonSchema?.input({ target: "draft-2020-12" });
-  } catch {
-    return;
-  }
+async function signatureHeaders(rawBody) {
+  if (!values.sign)
+    return {};
+  const scheme = schemes[values.sign] ?? fail(`Unknown scheme "${values.sign}", use one of: ${Object.keys(schemes).join(", ")}`);
+  const name = values["secret-env"] ?? fail("--sign needs --secret-env <name>");
+  const secret = process.env[name] ?? fail(`${name} is not set`);
+  return scheme.sign(rawBody, secret);
 }
 async function main() {
   if (values.help || !modulePath || !command) {
     console.log(HELP);
     return;
   }
+  for (const preload of values.preload ?? [])
+    await importModule(preload);
   const app = await loadApp(modulePath);
   if (command === "list") {
     for (const { config } of app.webhooks) {
-      const validates = ["params", "query", "headers", "body"].filter((key) => config[key]).join(", ");
+      const validates = [
+        ...["params", "query", "headers", "body"].filter((key) => config[key]),
+        ...config.verify ? ["signature"] : []
+      ].join(", ");
       console.log(`${config.method.padEnd(7)} ${config.path}${config.description ? `  ${config.description}` : ""}`);
       if (validates)
         console.log(`        validates ${validates}`);
@@ -70,22 +471,24 @@ async function main() {
   }
   if (command === "schema") {
     const [path] = args;
-    const matches = app.webhooks.filter((w) => w.config.path === path);
-    if (!matches.length)
+    const descriptions = describeWebhooks(app);
+    const indexes = app.webhooks.flatMap((w, i) => w.config.path === path ? [i] : []);
+    if (!indexes.length)
       fail(`No webhook at ${path}`);
-    for (const { config } of matches) {
+    for (const i of indexes) {
+      const { config } = app.webhooks[i];
       console.log(`${config.method} ${config.path}`);
-      for (const key of [
+      for (const part of [
         "params",
         "query",
         "headers",
         "body",
         "response"
       ]) {
-        if (!config[key])
+        if (!config[part])
           continue;
-        const json = jsonSchemaOf(config[key]);
-        console.log(`  ${key}: ${json ? JSON.stringify(json, null, 2).replaceAll(`
+        const schema = descriptions[i].jsonSchema[part];
+        console.log(`  ${part}: ${schema ? JSON.stringify(schema, null, 2).replaceAll(`
 `, `
   `) : "(no JSON Schema support)"}`);
       }
@@ -111,6 +514,9 @@ async function main() {
         headers.set("content-type", "text/plain");
       }
     }
+    for (const [name, value] of Object.entries(await signatureHeaders(values.body ?? ""))) {
+      headers.set(name, value);
+    }
     const url = `${path.startsWith("/") ? path : `/${path}`}${values.query ? `?${values.query}` : ""}`;
     const start = performance.now();
     const res = await app.request(url, {