feat: a webhook delivery can be proved to have come from Jira

jira.js/webhooks described what arrives and left the one question that matters unanswered: whether it arrived from
Jira at all. x-hub-signature is HMAC-SHA256 over the body's exact bytes, and verifying it was the reader's problem.

The subpath stops being types-only, but stays browser-safe and free of Node built-ins: crypto.subtle is a global in
both, so nothing is imported and the browser bundle does not move. The cost is a promise, which a webhook handler
already is.

Every untrustworthy delivery answers false alike — no header, another algorithm, a malformed digest, a wrong one —
because the caller's response to all four is the same and telling them apart tells them apart to whoever is probing
the endpoint. An empty secret throws instead, being a mistake rather than a failed check. The comparison is
constant-time, and the algorithm is pinned to RFC 4231's second vector rather than only to a signature of our own
making.

Author: MrRefactoring

CHANGELOG.md

@@ -112,7 +112,25 @@ Three long-standing requests, all of them the same shape: the client had no seam
   });
   ```
 
-  Types only — the subpath compiles to `export {}` and adds nothing to a bundle. There is no parser and no signature check: a webhook body is shaped by the site that sent it, custom fields and installed apps included, so a schema strict enough to be worth having would reject bodies that are perfectly valid elsewhere.
+  There is no parser: a webhook body is shaped by the site that sent it, custom fields and installed apps included, so a schema strict enough to be worth having would reject bodies that are perfectly valid elsewhere.
+
+  **`verifyWebhookSignature` is the one thing here that runs**, because it is the one claim that can be checked rather than asserted. `x-hub-signature` is what distinguishes a delivery from Jira from a POST anyone who found your URL can make, and it is HMAC-SHA256 over the exact bytes of the body.
+
+  ```ts
+  import { verifyWebhookSignature } from 'jira.js/webhooks';
+
+  app.post('/jira', express.raw({ type: 'application/json' }), async (request, response) => {
+    const trusted = await verifyWebhookSignature({
+      body: request.body,
+      secret: process.env.JIRA_WEBHOOK_SECRET!,
+      signature: request.get('x-hub-signature'),
+    });
+
+    if (!trusted) return response.sendStatus(401);
+  });
+  ```
+
+  The body must be the bytes that arrived — `JSON.stringify` of a parsed object is a different byte sequence for the same data, and never matches. Every untrustworthy delivery answers `false` alike, whether the header is missing, names another algorithm, or carries a digest of the right shape and the wrong value; only an empty secret throws, being a mistake of yours rather than a failed check. The comparison is constant-time, and `crypto.subtle` is a global in Node and browsers alike, so nothing is imported and the browser bundle is unchanged.
 
   How much is documented is worth stating plainly, because the types say it too. Atlassian publishes one complete payload, the one for issue events; that group is written from it and from a capture of a real delivery, and is the only one whose entity is required. Every other group names its entity optionally, after the entity the event concerns. The headers are lower-cased, as they arrive, and every value is typed as the string an HTTP header is — the retry count included.
 

docs/guide/webhooks.md

@@ -91,23 +91,56 @@ built on it. Every value is a string, including the retry count: an HTTP header
 | `x-atlassian-webhook-flow` | `Primary` for the event itself, thirty seconds; `Secondary` for the fallout of a bulk or cascading change, fifteen minutes |
 | `x-atlassian-webhook-retry` | how many retries so far; absent on the first attempt |
 | `x-atlassian-webhook-trace` | whatever a Connect app attached to the request that caused the event |
-| `x-hub-signature` | `sha256=…`, present only on a webhook registered with a secret |
+| `x-hub-signature` | `sha256=…`, present only on a webhook registered with a secret — pass it to `verifyWebhookSignature` |
 
 Deleting an issue is the clearest illustration of the flow header: `jira:issue_deleted` goes out as `Primary`, and
 every dependent `comment_deleted`, `attachment_deleted` and `issuelink_deleted` follows as `Secondary`, possibly
 minutes later.
 
-## What this does not do
+## There is no parser
 
-**It does not parse.** The casts above are the interface, deliberately. A webhook body is shaped by the site that sent
+The casts above are the interface, deliberately. A webhook body is shaped by the site that sent
 it — custom fields under generated keys in `issue.fields`, whatever an installed app adds, a Data Center release that
 differs from Cloud — and a schema strict enough to be worth having would reject bodies that are perfectly valid
 somewhere else. Elsewhere in this library a response is validated because the API documents it; here there is nothing
 to validate against.
 
-**It does not verify signatures.** `x-hub-signature` is the only thing that proves a request came from Jira rather
-than from whoever found your URL, and checking it is yours to do. This library does not, because a signature check
-that quietly compares the wrong way is worse than none, and there is nothing here to test one against.
+## Verifying the signature
+
+`x-hub-signature` is the only thing that proves a request came from Jira rather than from whoever found your URL. A
+webhook registered with a secret carries it as `sha256=<hex>`, over HMAC-SHA256 of the exact bytes of the body.
+
+```ts
+import express from 'express';
+import { verifyWebhookSignature, type WebhookPayload } from 'jira.js/webhooks';
+
+app.post('/jira', express.raw({ type: 'application/json' }), async (request, response) => {
+  const trusted = await verifyWebhookSignature({
+    body: request.body,
+    secret: process.env.JIRA_WEBHOOK_SECRET!,
+    signature: request.get('x-hub-signature'),
+  });
+
+  if (!trusted) return response.sendStatus(401);
+
+  const payload = JSON.parse(request.body.toString()) as WebhookPayload;
+
+  response.sendStatus(200);
+});
+```
+
+**The body must be the bytes that arrived.** This is where the check usually goes wrong: `express.json()` and every
+equivalent hand you a parsed object, and `JSON.stringify` of that object is a different byte sequence for the same
+data — key order, whitespace and number formatting are not preserved — so the signature will never match. Reach for
+whatever your framework calls a raw body.
+
+The answer is `false` for every way a delivery can fail to be trustworthy: no header, an algorithm other than
+`sha256`, a digest that is not hexadecimal, a digest of the right shape and the wrong value. Your response to all four
+is the same, and distinguishing them would distinguish them for whoever is probing the endpoint too. The one thing it
+throws on is an empty secret, which is a mistake of yours rather than a failed check.
+
+The comparison is constant-time, and nothing is imported to do any of it: `crypto.subtle` is a global in Node and in
+browsers alike, so this subpath still adds nothing to a browser bundle.
 
 ## Registering one
 

docs/ru/guide/webhooks.md

@@ -91,22 +91,55 @@ case 'jira:issue_updated':
 | `x-atlassian-webhook-flow` | `Primary` — само событие, тридцать секунд; `Secondary` — последствия массовой или каскадной операции, пятнадцать минут |
 | `x-atlassian-webhook-retry` | сколько было повторов; при первой попытке отсутствует |
 | `x-atlassian-webhook-trace` | то, что Connect-приложение приложило к запросу, вызвавшему событие |
-| `x-hub-signature` | `sha256=…`, только у вебхука, зарегистрированного с секретом |
+| `x-hub-signature` | `sha256=…`, только у вебхука, зарегистрированного с секретом — передайте в `verifyWebhookSignature` |
 
 Удаление задачи лучше всего показывает смысл заголовка потока: `jira:issue_deleted` уходит как `Primary`, а все
 зависимые `comment_deleted`, `attachment_deleted` и `issuelink_deleted` — следом как `Secondary`, возможно через
 несколько минут.
 
-## Чего здесь нет
+## Разбора здесь нет
 
-**Разбора.** Приведения типов выше — и есть интерфейс, намеренно. Тело вебхука определяется сайтом, который его послал:
+Приведения типов выше — и есть интерфейс, намеренно. Тело вебхука определяется сайтом, который его послал:
 пользовательские поля под сгенерированными ключами в `issue.fields`, что угодно от установленного приложения, релиз
 Data Center, отличающийся от Cloud. Схема, достаточно строгая, чтобы её стоило иметь, отвергала бы тела, совершенно
 правильные где-то ещё. В остальной библиотеке ответ валидируется, потому что API его описывает; здесь описывать нечем.
 
-**Проверки подписи.** `x-hub-signature` — единственное, что доказывает, что запрос пришёл от Jira, а не от того, кто
-нашёл ваш URL, и проверять его вам. Библиотека этого не делает: проверка подписи, которая тихо сравнивает не то, хуже
-её отсутствия, а протестировать её здесь не на чем.
+## Проверка подписи
+
+`x-hub-signature` — единственное, что доказывает, что запрос пришёл от Jira, а не от того, кто нашёл ваш URL. Вебхук,
+зарегистрированный с секретом, несёт её как `sha256=<hex>` — HMAC-SHA256 по точным байтам тела.
+
+```ts
+import express from 'express';
+import { verifyWebhookSignature, type WebhookPayload } from 'jira.js/webhooks';
+
+app.post('/jira', express.raw({ type: 'application/json' }), async (request, response) => {
+  const trusted = await verifyWebhookSignature({
+    body: request.body,
+    secret: process.env.JIRA_WEBHOOK_SECRET!,
+    signature: request.get('x-hub-signature'),
+  });
+
+  if (!trusted) return response.sendStatus(401);
+
+  const payload = JSON.parse(request.body.toString()) as WebhookPayload;
+
+  response.sendStatus(200);
+});
+```
+
+**Телом должны быть пришедшие байты.** Именно здесь проверка обычно и ломается: `express.json()` и всё ему подобное
+отдают разобранный объект, а `JSON.stringify` от него — уже другая последовательность байтов для тех же данных:
+порядок ключей, пробелы и запись чисел не сохраняются, и подпись не совпадёт никогда. Возьмите то, что ваш фреймворк
+называет сырым телом.
+
+Ответ — `false` на любой способ доставке оказаться недостоверной: заголовка нет, алгоритм не `sha256`, дайджест не
+шестнадцатеричный, дайджест нужной формы и неверного значения. Ваша реакция на все четыре одинакова, а различать их
+означало бы различать их и для того, кто прощупывает эндпоинт. Исключение бросается только на пустой секрет — это
+ошибка ваша, а не провалившаяся проверка.
+
+Сравнение идёт за постоянное время, и ради всего этого ничего не импортируется: `crypto.subtle` — глобальный объект и
+в Node, и в браузере, так что сабпать по-прежнему ничего не добавляет к браузерной сборке.
 
 ## Как зарегистрировать
 

scripts/checkConsumers.ts

@@ -65,9 +65,7 @@ try {
     .filter(entry => entry !== './browser' && entry !== './package.json')
     .map(entry => (entry === '.' ? 'jira.js' : `jira.js/${entry.slice(2)}`));
 
-  // `jira.js/webhooks` describes what Jira posts to a server of yours; there is nothing to call, so it compiles to
-  // `export {}`. An empty namespace is the right answer there, and a populated one would mean runtime code crept in.
-  const TYPES_ONLY = ['jira.js/webhooks'];
+  const TYPES_ONLY: string[] = [];
 
   const runtimeProbe = [
     ...SUBPATHS.map((subpath, index) => `import * as m${index} from '${subpath}';`),

src/webhooks/headers.ts

@@ -38,8 +38,8 @@ export interface WebhookHeaders {
    * The body's signature, as `method=signature` — `sha256=…` in practice. Present only on a webhook registered with
    * a secret, and the only thing that tells you the request really came from Jira.
    *
-   * Verifying it is yours to do. This library does not, because a signature check that quietly matches the wrong way
-   * is worse than none, and it cannot be tested against anything here.
+   * Pass it to `verifyWebhookSignature` along with the raw body and the secret you registered. A delivery that fails
+   * that check is one anyone could have sent.
    */
   'x-hub-signature'?: string;
 }

src/webhooks/index.ts

@@ -22,12 +22,17 @@
  * });
  * ```
  *
- * Types only, and deliberately: this subpath compiles away to nothing. There is no parser and no signature check,
- * because a webhook body is shaped by the site that sent it — custom fields, apps, a Data Center release Atlassian
- * documents separately — and a schema strict enough to be worth having would throw on bodies that are perfectly
- * valid. The cast above is the honest interface: you are telling the compiler what Jira sends, and this subpath is
- * where that claim is written down.
+ * There is no parser, and deliberately so: a webhook body is shaped by the site that sent it — custom fields, apps, a
+ * Data Center release Atlassian documents separately — and a schema strict enough to be worth having would throw on
+ * bodies that are perfectly valid. The cast above is the honest interface: you are telling the compiler what Jira
+ * sends, and this subpath is where that claim is written down.
+ *
+ * The one thing here that runs is `verifyWebhookSignature`, because it is the one claim that can be checked rather
+ * than asserted. HMAC-SHA256 over the raw body either matches the secret you registered or it does not, and until it
+ * does you know nothing about where the request came from.
  */
+export { verifyWebhookSignature, type VerifyWebhookSignatureOptions } from './verify';
+
 export type {
   WebhookEvent,
   IssueWebhookEvent,

src/webhooks/verify.ts

@@ -0,0 +1,132 @@
+/**
+ * Checks that a webhook body really came from your Jira site.
+ *
+ * A webhook registered with a secret arrives signed: Jira computes HMAC-SHA256 over the exact bytes of the request
+ * body and sends the digest as `X-Hub-Signature: sha256=<hex>`. Recomputing it with the same secret is the only thing
+ * that distinguishes a delivery from Jira from a POST anyone on the internet can make to the same URL.
+ *
+ * ```ts
+ * import { verifyWebhookSignature } from 'jira.js/webhooks';
+ *
+ * app.post('/jira', express.raw({ type: 'application/json' }), async (request, response) => {
+ *   const trusted = await verifyWebhookSignature({
+ *     body: request.body,
+ *     secret: process.env.JIRA_WEBHOOK_SECRET!,
+ *     signature: request.get('x-hub-signature'),
+ *   });
+ *
+ *   if (!trusted) return response.sendStatus(401);
+ *
+ *   const payload = JSON.parse(request.body.toString()) as WebhookPayload;
+ * });
+ * ```
+ *
+ * The body must be the bytes that arrived. Re-serialising a parsed object — `JSON.stringify(request.body)` — produces
+ * a different byte sequence for the same data, because key order, whitespace and number formatting are not preserved,
+ * and the signature will not match. Every framework has a way to keep the raw body; use it.
+ *
+ * Nothing here is imported: `crypto.subtle` is a global in Node 18 and later and in every browser, so this subpath
+ * stays free of Node built-ins and the browser bundle is unaffected.
+ */
+
+/** How a signature was computed. Jira sends `sha256`; nothing else is accepted. */
+const ALGORITHM = 'sha256';
+
+export interface VerifyWebhookSignatureOptions {
+  /**
+   * The raw request body, exactly as it arrived — not a parsed object re-serialised, whose bytes differ from what was
+   * signed.
+   */
+  body: string | ArrayBuffer | Uint8Array;
+
+  /** The secret you gave Jira when you registered the webhook. */
+  secret: string;
+
+  /**
+   * The `X-Hub-Signature` header. Passing `undefined` is the ordinary case of an unsigned delivery and answers
+   * `false`, so a missing header needs no separate branch of yours.
+   */
+  signature: string | undefined;
+}
+
+/**
+ * Copies into an array `crypto.subtle` accepts.
+ *
+ * `BufferSource` excludes a view onto a `SharedArrayBuffer`, which a plain `Uint8Array` may be; constructing a new one
+ * both narrows the type and respects the offset and length of a view onto a larger buffer, which a webhook body read
+ * out of a pooled buffer usually is.
+ */
+function toBytes(value: string | ArrayBuffer | Uint8Array): Uint8Array<ArrayBuffer> {
+  if (typeof value === 'string') return new TextEncoder().encode(value);
+
+  return new Uint8Array(value);
+}
+
+function fromHex(hex: string): Uint8Array | undefined {
+  if (hex.length === 0 || hex.length % 2 !== 0 || !/^[0-9a-f]+$/i.test(hex)) return undefined;
+
+  const bytes = new Uint8Array(hex.length / 2);
+
+  for (let index = 0; index < bytes.length; index++) {
+    bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+  }
+
+  return bytes;
+}
+
+/**
+ * Compares two digests without letting the time taken reveal how far they matched.
+ *
+ * A `===` on hex strings stops at the first differing character, and an attacker who can send many deliveries and
+ * measure the replies can recover a valid signature one character at a time. Differing lengths are answered at once
+ * on purpose: the length of a digest is public, its contents are not.
+ */
+function equalInConstantTime(left: Uint8Array, right: Uint8Array): boolean {
+  if (left.length !== right.length) return false;
+
+  let difference = 0;
+
+  for (let index = 0; index < left.length; index++) difference |= left[index]! ^ right[index]!;
+
+  return difference === 0;
+}
+
+/**
+ * Whether the body carries a signature this secret produces.
+ *
+ * Answers `false` for every way a delivery can fail to be trustworthy — no header, an algorithm other than `sha256`,
+ * a digest that is not hexadecimal, a digest of the right shape and the wrong value — because a handler's response to
+ * all four is the same, and telling them apart to the caller would tell them apart to whoever is probing the endpoint.
+ *
+ * Throws only on a mistake of yours: an empty secret would make every delivery verify against a value an attacker can
+ * compute, so it is a programming error rather than a failed check.
+ */
+export async function verifyWebhookSignature(options: VerifyWebhookSignatureOptions): Promise<boolean> {
+  const { body, secret, signature } = options;
+
+  if (secret.length === 0) {
+    throw new TypeError('verifyWebhookSignature: the secret is empty, which would verify every body ever sent');
+  }
+
+  if (signature === undefined) return false;
+
+  const separator = signature.indexOf('=');
+
+  if (signature.slice(0, separator) !== ALGORITHM) return false;
+
+  const sent = fromHex(signature.slice(separator + 1));
+
+  if (sent === undefined) return false;
+
+  const key = await crypto.subtle.importKey(
+    'raw',
+    toBytes(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  );
+
+  const computed = new Uint8Array(await crypto.subtle.sign('HMAC', key, toBytes(body)));
+
+  return equalInConstantTime(computed, sent);
+}