verify webhook signature + update webhook schema and types

Author: gh-workflow-token-generator[bot]

.changeset/light-starfishes-build.md

@@ -0,0 +1,11 @@
+---
+'@team-plain/typescript-sdk': major
+---
+
+Upgrade the SDK webhook parsing to support webhook version '2024-09-18'.
+
+### Breaking Changes
+If your Plain webhook target is on the legacy/unversioned version, the SDK will no longer be able to parse the webhook payload. You must update your webhook target to '2024-09-18'. Refer to [our docs](https://www.plain.com/docs/api-reference/webhooks/versions) for more information and instructions on how to safely upgrade your webhook target.
+
+### Added
+`verifyPlainWebhook` method to verify the webhook signature, with support for replay attack protection, and parse the webhook payload. Refer to the [README](./README.md) for usage instructions.

README.md

@@ -1,6 +1,6 @@
 # @team-plain/typescript-sdk
 
-[Changelog]('./CHANGELOG.md')
+[Changelog](./CHANGELOG.md)
 
 ## Plain Client
 
@@ -104,16 +104,38 @@ Fallback error type when something unexpected happens.
 
 ## Webhooks
 
-This package also provides functionality to validate our [Webhook payloads](https://www.plain.com/docs/api-reference/webhooks).
+Plain signs the [webhooks](https://www.plain.com/docs/api-reference/webhooks) it sends to your endpoint,
+allowing you to validate that they were not sent by a third-party. You can read more about it [here](https://www.plain.com/docs/api-reference/request-signing).
+The SDK provides a convenient helper function to verify the signature, prevent replay attacks, and parse the payload to a typed object.
 
 ```ts
-import { parsePlainWebhook } from '@team-plain/typescript-sdk';
-
-const payload = { ... };
-
-if(parsePlainWebhook(payload)) {
-  // payload is now typed!
-  doYourThing(payload);
+import { verifyPlainWebhook, PlainWebhookSignatureVerificationError, PlainWebhookVersionMismatchError } from '@team-plain/typescript-sdk';
+
+// Please note that you must pass the raw request body, exactly as received from Plain,
+// to the verifyPlainWebhook() function; this will not work with a parsed (i.e., JSON) request body.
+const payload = '...';
+
+// The value of the `Plain-Request-Signature` header from the webhook request.
+const signature = '...';
+
+// Plain Request Signature Secret. You can find this in Plain's settings.
+const secret = '...';
+
+try {
+  const webhook = verifyPlainWebhook(payload, signature, secret);
+  // webhook is now a typed object.
+} catch (error) {
+  if (error instanceof PlainWebhookSignatureVerificationError) {
+    // Signature verification failed.
+  } else if (error instanceof PlainWebhookVersionMismatchError) {
+    // The SDK is not compatible with the received webhook version.
+    // Consider updating the SDK and the webhook target to the latest version.
+    // Consult the changelog or https://plain.com/docs/api-reference/webhooks/versions for more information.
+  } else {
+    // Unexpected error. Most likely due to an error in Plain's webhook server or a bug in the SDK.
+    // Treate this as a 500 response from Plain.
+    // We also recommend logging the error and sharing it with Plain's support team.
+  }
 }
 ```
 

biome.json

@@ -23,7 +23,12 @@
     }
   },
   "files": {
-    "include": ["biome.json", "vitest.*.js", "src/**/*.ts", "src/**/*.gql"],
+    "include": [
+      "biome.json",
+      "vitest.*.js",
+      "src/**/*.ts",
+      "src/**/*.gql"
+    ],
     "ignore": [
       "dist/**",
       "node_modules/**",
@@ -59,4 +64,4 @@
   "organizeImports": {
     "enabled": true
   }
-}
+}

package.json

@@ -31,6 +31,7 @@
     "@graphql-codegen/typescript-document-nodes": "^3.0.4",
     "@graphql-codegen/typescript-operations": "^3.0.4",
     "@rollup/plugin-json": "^6.1.0",
+    "@types/lodash.get": "^4.4.9",
     "esbuild": "^0.17.18",
     "json-schema-to-typescript": "^13.1.2",
     "rollup": "^3.21.5",
@@ -46,6 +47,7 @@
     "ajv": "^8.12.0",
     "ajv-formats": "^2.1.1",
     "graphql": "^16.6.0",
+    "lodash.get": "^4.4.2",
     "zod": "3.22.4"
   }
 }

pnpm-lock.yaml

@@ -1,7 +1,6 @@
 
 #!/bin/bash
-
 # Download the JSON schema
-curl https://core-api.uk.plain.com/webhooks/schema.json -o ./src/webhooks/webhook-schema.json
+curl https://core-api.uk.plain.com/webhooks/schema/latest.json -o ./src/webhooks/webhook-schema.json
 
-./node_modules/.bin/json2ts --input ./src/webhooks/webhook-schema.json --output ./src/webhooks/webhook-schema.ts
+./node_modules/.bin/json2ts --input ./src/webhooks/webhook-schema.json --output ./src/webhooks/webhook-schema.ts

scripts/codegen-webhooks.sh

@@ -11,3 +11,7 @@ type Err<U> = {
 };
 
 export type Result<T, U> = NonNullable<Data<T> | Err<U>>;
+
+export const isErr = <T, U>(result: Result<T, U>): result is Err<U> => {
+  return !!result.error;
+};

src/result.ts

@@ -1,5 +1,6 @@
-import { describe, expect, test } from 'vitest';
+import { describe, expect, it, test } from 'vitest';
 
+import { PlainWebhookPayloadError, PlainWebhookVersionMismatchError } from '../webhooks/errors';
 import { parsePlainWebhook } from '../webhooks/parse';
 import customerCreatedPayload from './webhook-payloads/customer-created';
 import emailReceivedPayload from './webhook-payloads/email-received';
@@ -24,4 +25,44 @@ describe('Parse webhook', () => {
   test('should fail to validate an invalid payload', () => {
     expect(parsePlainWebhook(invalidWebhook).error).toBeTruthy();
   });
+
+  it('accepts a stringified payload', () => {
+    const result = parsePlainWebhook(JSON.stringify(threadCreatedPayload));
+    expect(result.data).toBeTruthy();
+  });
+
+  it('returns a human-readable error message when the payload is not a valid webhook payload', () => {
+    const invalidPayload = {
+      ...threadCreatedPayload,
+      payload: {
+        ...threadCreatedPayload.payload,
+        thread: {
+          ...threadCreatedPayload.payload.thread,
+          title: undefined,
+        },
+      },
+    };
+
+    const result = parsePlainWebhook(invalidPayload);
+
+    expect(result.error).instanceOf(PlainWebhookPayloadError);
+    expect(result.error?.message).toBe("data/payload/thread must have required property 'title'");
+  });
+
+  it('returns a version mismatch error', () => {
+    const invalidWebhook = {
+      ...threadCreatedPayload,
+      webhookMetadata: {
+        ...threadCreatedPayload.webhookMetadata,
+        webhookTargetVersion: 'NEW_VERSION',
+      },
+    };
+
+    const result = parsePlainWebhook(invalidWebhook);
+
+    expect(result.error).instanceOf(PlainWebhookVersionMismatchError);
+    expect(result.error?.message).toBe(
+      'The webhook payload is not compatible with the current version of the Plain API.'
+    );
+  });
 });

src/tests/parse-webhook.test.ts

@@ -0,0 +1,109 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  PlainWebhookPayloadError,
+  PlainWebhookSignatureVerificationError,
+} from '../webhooks/errors';
+import { verifyPlainWebhook } from '../webhooks/verify';
+import threadCreatedPayload from './webhook-payloads/thread-created';
+
+describe('verifyPlainWebhook', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('returns an error when the payload is empty', () => {
+    const result = verifyPlainWebhook('', 'signature', 'secret');
+
+    expect(result.error).instanceOf(PlainWebhookSignatureVerificationError);
+    expect(result.error?.message).toBe('No webhook payload was provided.');
+  });
+
+  it('returns an error when the signature is empty', () => {
+    const result = verifyPlainWebhook('payload', '', 'secret');
+
+    expect(result.error).instanceOf(PlainWebhookSignatureVerificationError);
+    expect(result.error?.message).toBe(
+      'No signature header value was provided. Please pass the value of the "Plain-Request-Signature" header.'
+    );
+  });
+
+  it('returns an error when the secret is empty', () => {
+    const result = verifyPlainWebhook('payload', 'signature', '');
+
+    expect(result.error).instanceOf(PlainWebhookSignatureVerificationError);
+    expect(result.error?.message).toBe(
+      'No webhook secret was provided. You can find your webhook secret in your workspace settings.'
+    );
+  });
+
+  it('returns an error when the signature does not match', () => {
+    const result = verifyPlainWebhook('payload', 'signature', 'secret');
+
+    expect(result.error).instanceOf(PlainWebhookSignatureVerificationError);
+    expect(result.error?.message).toBe('The signature provided is invalid.');
+  });
+
+  it('returns an error when the signature matches but the timestamp is too far in the past', () => {
+    const result = verifyPlainWebhook(
+      JSON.stringify(threadCreatedPayload),
+      'c593af32704c178b404c3de8d32ae54c038f4901349c4c55454f1b7952c25e76',
+      'secret'
+    );
+
+    expect(result.error).instanceOf(PlainWebhookSignatureVerificationError);
+    expect(result.error?.message).toBe(
+      'The timestamp provided in the webhook payload is too far in the past. The maximum allowed difference is 300 seconds.'
+    );
+  });
+
+  it("doesn't return an error when the signature matches and the timestamp is within the tolerance", () => {
+    // +5 minutes - 1 second
+    vi.setSystemTime(new Date(Date.UTC(2023, 9, 19, 14, 17, 26)));
+
+    const result = verifyPlainWebhook(
+      JSON.stringify(threadCreatedPayload),
+      'c593af32704c178b404c3de8d32ae54c038f4901349c4c55454f1b7952c25e76',
+      'secret'
+    );
+
+    expect(result.error).toBeUndefined();
+    expect(result.data?.type).toBe('thread.thread_created');
+  });
+
+  it('returns an error when the payload is not a valid JSON object', () => {
+    const result = verifyPlainWebhook(
+      'hello-world',
+      '1bff4699de4fb5202a4b1e6cefd7b5fdfb02d19a67a1eb371dd417a45b0a47df',
+      'secret'
+    );
+
+    expect(result.error).instanceOf(PlainWebhookPayloadError);
+    expect(result.error?.message).toBe('The webhook payload is not a valid JSON object.');
+  });
+
+  it('returns an error when the payload is not a valid webhook payload', () => {
+    const invalidPayload = {
+      ...threadCreatedPayload,
+      payload: {
+        ...threadCreatedPayload.payload,
+        thread: {
+          ...threadCreatedPayload.payload.thread,
+          title: undefined,
+        },
+      },
+    };
+
+    const result = verifyPlainWebhook(
+      JSON.stringify(invalidPayload),
+      '239dbfc186e45ea30ead51cb741a2c5a2997fc0d932b8c85ed1c0ee49132e52f',
+      'secret'
+    );
+
+    expect(result.error).instanceOf(PlainWebhookPayloadError);
+    expect(result.error?.message).toBe("data/payload/thread must have required property 'title'");
+  });
+});

src/tests/verify-plain-webhook.test.ts

@@ -0,0 +1,13 @@
+export abstract class PlainWebhookError extends Error {}
+
+export class PlainWebhookSignatureVerificationError extends PlainWebhookError {}
+
+export class PlainWebhookVersionMismatchError extends PlainWebhookError {
+  constructor(payloadVersion: string, error: string) {
+    super(
+      `The webhook payload (version=${payloadVersion}) is incompatible with the current version of the SDK. Please upgrade both the SDK and the webhook target to the latest version. Refer to https://www.plain.com/docs/api-reference/webhooks/versions for more information. Original error: ${error}`
+    );
+  }
+}
+
+export class PlainWebhookPayloadError extends PlainWebhookError {}