feat(js-api-client): Crystallize Signature helper

Author: Plopix

README.md

@@ -20,6 +20,7 @@ So far, the available helpers are:
 -   Folders
 -   CustomerManager
 -   Subscription Contract Manager
+-   Signature Verification
 
 ## Installation
 
@@ -473,6 +474,39 @@ An Update method exists as well:
 await CrystallizeSubscriptionContractManager.update(contractId, cleanUpdateContract);
 ```
 
+## Signature Verification
+
+The full documentation is here https://crystallize.com/learn/developer-guides/api-overview/signature-verification
+This library makes it simple, assuming:
+
+-   you have your `CRYSTALLIZE_SIGNATURE_SECRET` from the environment variable
+-   you retrieve the Signature from the Header in `signatureJwt`
+
+you can use the `createSignatureVerifier`
+
+```javascript
+const guard = createSignatureVerifier({
+    secret: `${process.env.CRYSTALLIZE_SIGNATURE_SECRET}`,
+    sha256: (data: string) => crypto.createHash('sha256').update(data).digest('hex'),
+    jwtVerify: (token: string, secret: string) => jwt.verify(token, secret) as CrystallizeSignature,
+});
+
+guard(signatureJwt, {
+    url: request.url, // full URL here, including https://  etc. request.href in some framework
+    method: 'POST',
+    body: 'THE RAW JSON BODY', // the library parse it for you cf. doc
+});
+```
+
+If the signature is not valid:
+
+-   JWT signature is not verified
+-   HMAC is invalid (man in the middle)
+
+The guard function will trigger an exception.
+
+> We let you provide the `sha256` and `jwtVerify` methods to stay agnostic of any library.
+
 ## Mass Call Client
 
 Sometimes, when you have many calls to do, whether they are queries or mutations, you want to be able to manage them asynchronously. This is the purpose of the Mass Call Client. It will let you be asynchronous, managing the heavy lifting of lifecycle, retry, incremental increase or decrease of the pace, etc.

package.json

@@ -1,7 +1,7 @@
 {
     "name": "@crystallize/js-api-client",
     "license": "MIT",
-    "version": "1.9.1",
+    "version": "1.10.0",
     "author": "Crystallize <[email protected]> (https://crystallize.com)",
     "contributors": [
         "Sébastien Morel <[email protected]>"

src/core/verifySignature.ts

@@ -0,0 +1,36 @@
+import { CrystallizeSignature } from '../types/signature';
+
+export type SimplifiedRequest = {
+    url?: string;
+    method?: string;
+    body?: any;
+};
+
+export type CreateSignatureVerifierParams = {
+    sha256: (data: string) => string;
+    jwtVerify: (token: string, secret: string, options?: any) => CrystallizeSignature;
+    secret: string;
+};
+
+export const createSignatureVerifier = ({ sha256, jwtVerify, secret }: CreateSignatureVerifierParams) => {
+    return (signature: string, request: SimplifiedRequest): any => {
+        try {
+            const payload = jwtVerify(signature, secret);
+            const isValid =
+                payload.hmac ===
+                sha256(
+                    JSON.stringify({
+                        url: request.url,
+                        method: request.method,
+                        body: JSON.parse(request.body),
+                    }),
+                );
+            if (!isValid) {
+                throw new Error('Invalid signature. HMAC does not match');
+            }
+            return payload;
+        } catch (exception: any) {
+            throw new Error('Invalid signature. ' + exception.message);
+        }
+    };
+};

src/index.ts

@@ -8,6 +8,7 @@ export * from './core/search';
 export * from './core/subscription';
 export * from './core/customer';
 export * from './core/pricing';
+export * from './core/verifySignature';
 export * from './types/product';
 export * from './types/order';
 export * from './types/payment';

src/types/signature.ts

@@ -7,4 +7,5 @@ export type CrystallizeSignature = {
     userId?: string;
     tenantId: string;
     tenantIdentifier: string;
+    hmac: string;
 };

tests/signature.test.js

@@ -0,0 +1,20 @@
+const { createSignatureVerifier } = require('../dist/index.js');
+var crypto = require('crypto');
+
+test('Test Signature HMAC', () => {
+    const guard = createSignatureVerifier({
+        secret: 'xXx',
+        sha256: (data) => crypto.createHash('sha256').update(data).digest('hex'),
+        jwtVerify: (token, secret) => ({
+            hmac: '1101b34dac8c55e5590a37271f1c41c3d745463854613494a1624a15be24f1f8',
+        }),
+    });
+
+    expect(
+        guard('xXx.xXx.xXx', {
+            url: 'https://a17e-2601-645-4500-330-b07d-351d-ece7-41c1.ngrok.io/test/signature',
+            method: 'POST',
+            body: '{"item":{"get":{"id":"63f2d3b2a94533f79fc6397b","createdAt":"2023-02-20T01:58:10.000Z","updatedAt":"2023-02-23T07:58:34.685Z","name":"test"}}}',
+        }),
+    );
+});