hx-ext-amz-content-sha256 1.0.0

package/LICENSE

@@ -0,0 +1,14 @@
+BSD Zero Clause License
+
+Copyright (c) 2023, Alexander Petros
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+## HTMX Extension: amz-content-sha256
+
+### Overview
+
+`amz-content-sha256` is a htmx extension that adds an additional header to POST and PUT requests made from a form. This header is called `x-amz-content-sha256` and it contains a SHA-256 hash of the form data. This extension is particularly useful for interacting with AWS services that require the content hash as part of the request for data integrity verification.
+
+The extension computes the SHA-256 hash of the form data and attaches it to the request header, ensuring that the data sent is not tampered with in transit. This is especially important for certain AWS services that use this hash to validate the integrity of the data sent to APIs, such as AWS Lambda behind CloudFront.
+
+### Why Do You Need This?
+
+Some AWS services, like Lambda functions behind CloudFront, require clients to send a SHA-256 hash of the request data (e.g., form data) to ensure the integrity of the request. Without this hash, AWS might reject your requests, resulting in errors such as:
+
+_Error Example_:
+
+```json
+{
+  "message": "The request signature we calculated does not match the signature you provided. Check your AWS Secret Access Key and signing method. Consult the service documentation for details."
+}
+```
+
+This issue can occur when using Lambda Function URLs behind CloudFront, as explained in this [Aws Community Post](https://repost.aws/questions/QUbHCI9AfyRdaUPCCo_3XKMQ/lambda-function-url-behind-cloudfront-invalidsignatureexception-only-on-post). See the [AWS Docs](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-lambda.html) that confirm that behaviour.
+
+### How Does It Work?
+
+1. Form Submission: When a form is submitted using a POST or PUT request, the extension calculates the SHA-256 hash of the form data.
+2. Header Addition: The calculated hash is added to the request as the header x-amz-content-sha256.
+3. Request Integrity: This header ensures that the data sent is valid and hasn't been altered, which is required for services such as Lambda behind CloudFront.
+
+### Installation
+
+1. Include the extension in your HTML page headers.
+2. Add the tag hx-ext="amz-content-sha256" to your desired form or even the document body if you want this behaviour for all post and put requests.
+3. Add a form element that will trigger a POST or PUT request.
+4. When the form is submitted, the extension will automatically compute the SHA-256 hash and add the x-amz-content-sha256 header to the request.
+
+_Example_:
+
+```html
+<form hx-post="/your-api-endpoint" hx-ext="amz-content-sha256">
+  <input type="text" name="example" value="test" />
+  <button type="submit">Submit</button>
+</form>
+```
+
+`

package/amz-content-sha256.js

@@ -0,0 +1,84 @@
+htmx.defineExtension("amz-content-sha256", {
+  init: function () {
+    /**
+     * The `init` method is called when the extension is initialized.
+     * It sets up an object `RequestHashQueue` that will store SHA-256 hashes for each POST/PUT request,
+     * categorized by the request path.
+     * It also defines an asynchronous function `calculateSHA256` that computes the SHA-256 hash required by AWS
+     * for data integrity verification.
+     */
+    this.RequestHashQueue = {}; // Queue to store hashes for each request path.
+
+    this.calculateSHA256 = async (data) => {
+      // Convert the data into a byte array using TextEncoder
+      const encoder = new TextEncoder();
+      const dataBuffer = encoder.encode(data);
+
+      // Calculate the SHA-256 hash of the data
+      const hashBuffer = await crypto.subtle.digest("SHA-256", dataBuffer);
+
+      // Convert the hash buffer into a hexadecimal string
+      const hashArray = Array.from(new Uint8Array(hashBuffer));
+      const hashHex = hashArray
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+
+      return hashHex; // Return the hex representation of the SHA-256 hash
+    };
+
+    return null; // Nothing needs to be returned from `init`
+  },
+
+  onEvent: async function (name, e) {
+    switch (name) {
+      case "htmx:confirm":
+        /**
+         * This event is triggered when a form submission is confirmed.
+         * If the request method is POST or PUT, we process the form data and calculate its SHA-256 hash.
+         * The hash is then added to the `RequestHashQueue` for the specific request path.
+         * If the queue already exists for that path, the new hash is appended to the queue.
+         */
+        if (e.detail.verb == "post" || e.detail.verb == "put") {
+          e.preventDefault(); // Prevent the default form submission to handle it programmatically.
+
+          const form = e.target; // The form element that triggered the event.
+
+          // Ensure the target is a valid HTMLFormElement
+          if (form instanceof HTMLFormElement) {
+            // Create a FormData object from the form, and convert it into a URLSearchParams string
+            const formData = new FormData(form);
+            const data = new URLSearchParams(formData).toString();
+
+            // Calculate the SHA-256 hash of the form data
+            const sha256Hash = await this.calculateSHA256(data);
+
+            // Check if there's already a hash queue for this path, and either initialize or append to it
+            if (!this.RequestHashQueue[e.detail.path]) {
+              this.RequestHashQueue[e.detail.path] = [sha256Hash];
+            } else {
+              this.RequestHashQueue[e.detail.path].push(sha256Hash);
+            }
+          }
+
+          // Proceed with the request after processing the form data and hash
+          e.detail.issueRequest();
+        }
+        break;
+
+      case "htmx:configRequest":
+        /**
+         * Before the actual request is sent to AWS, if it is a POST or PUT request,
+         * this event is triggered. Here, we retrieve the SHA-256 hash from the `RequestHashQueue`
+         * and add it to the request headers under the name `x-amz-content-sha256`.
+         * This header is necessary for AWS services to validate the integrity of the request payload.
+         */
+        if (e.detail.verb == "post" || e.detail.verb == "put") {
+          // If there is a hash in the queue for the current request path, add it to the request header
+          if (this.RequestHashQueue[e.detail.path].length > 0)
+            e.detail.headers["x-amz-content-sha256"] =
+              this.RequestHashQueue[e.detail.path].pop();
+        }
+        break;
+    }
+  },
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "hx-ext-amz-content-sha256",
+  "main": "amz-content-sha256.js",
+  "version": "1.0.0",
+  "scripts": {
+    "lint": "eslint test/ext test",
+    "lint-fix": "eslint test/ext test --fix",
+    "format": "eslint --fix test/ext test",
+    "test": "mocha-chrome test/index.html"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/felipegenef/amz-content-sha256.git"
+  },
+  "devDependencies": {
+    "chai": "^4.3.10",
+    "chai-dom": "^1.12.0",
+    "mocha": "10.1.0",
+    "mocha-chrome": "https://github.com/Telroshan/mocha-chrome",
+    "sinon": "^9.2.4",
+    "htmx.org": "^2.0.2"
+  }
+}

package/test/ext/test.js

@@ -0,0 +1,87 @@
+describe("Create a hash from a request", function () {
+  beforeEach(function () {
+    this.server = makeServer();
+    clearWorkArea();
+  });
+  afterEach(function () {
+    this.server.restore();
+    clearWorkArea();
+  });
+
+  it("Should hash the request if it is a post", async function () {
+    this.server.respondWith("POST", "/test", function (xhr) {
+      xhr.respond(
+        200,
+        {},
+        JSON.stringify({ hash: xhr.requestHeaders["x-amz-content-sha256"] })
+      );
+    });
+
+    var html = make(
+      '<form hx-post="/test" hx-ext="amz-content-sha256" > ' +
+        '<input type="text"  name="email" value="email@email.com"> ' +
+        '<input type="password"  name="password" value="123456"> ' +
+        '<button  id="btnSubmit">Submit</button> '
+    );
+
+    byId("btnSubmit").click();
+    // Await for async crypto hash function
+    await new Promise((res) => setTimeout(res, 100));
+    this.server.respond();
+    this.server.lastRequest.response.should.equal(
+      '{"hash":"9e2fbbb1b4b2e1cabd1923ec1376ab3c57b904820101b6edccf1a2c1adc20faf"}' // Hash for this first form data
+    );
+  });
+
+  it("Should hash the request if it is a put", async function () {
+    this.server.respondWith("PUT", "/test", function (xhr) {
+      xhr.respond(
+        200,
+        {},
+        JSON.stringify({ hash: xhr.requestHeaders["x-amz-content-sha256"] })
+      );
+    });
+
+    var html = make(
+      '<form hx-put="/test" hx-ext="amz-content-sha256" > ' +
+        '<input type="text"  name="email" value="email2@email.com"> ' +
+        '<input type="password"  name="password" value="123456"> ' +
+        '<button  id="btnSubmit">Submit</button> '
+    );
+
+    byId("btnSubmit").click();
+    // Await for async crypto hash function
+    await new Promise((res) => setTimeout(res, 100));
+    this.server.respond();
+    this.server.lastRequest.response.should.equal(
+      '{"hash":"31b0fe62efaa67d156b565b8d5221c3e7fdf2201f52f9adcd955d36614c65f59"}' // Hash for this first form data
+    );
+  });
+
+  it("Should not send a hash if there is no form element", async function () {
+    this.server.respondWith("POST", "/test", function (xhr) {
+      const hashNotSend =
+        xhr.requestHeaders["x-amz-content-sha256"] == undefined;
+      xhr.respond(
+        200,
+        {},
+        JSON.stringify({
+          hashNotSend,
+          hash: xhr.requestHeaders["x-amz-content-sha256"],
+        })
+      );
+    });
+
+    var html = make(
+      '<button hx-post="/test" hx-ext="amz-content-sha256"  id="btnSubmit">Submit</button> '
+    );
+
+    byId("btnSubmit").click();
+    // Await for async crypto hash function
+    await new Promise((res) => setTimeout(res, 100));
+    this.server.respond();
+    this.server.lastRequest.response.should.equal(
+      '{"hashNotSend":true}' // Hash for this first form data
+    );
+  });
+});

package/test/index.html

@@ -0,0 +1,69 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <title>Mocha Tests</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="stylesheet" href="../node_modules/mocha/mocha.css" />
+    <meta http-equiv="cache-control" content="no-cache, must-revalidate, post-check=0, pre-check=0" />
+    <meta http-equiv="cache-control" content="max-age=0" />
+    <meta http-equiv="expires" content="0" />
+    <meta http-equiv="expires" content="Tue, 01 Jan 1980 1:00:00 GMT" />
+    <meta http-equiv="pragma" content="no-cache" />
+    <meta name="htmx-config" content='{"historyEnabled":false,"defaultSettleDelay":0,"head":{"boost":"none","other":"none"}}'>
+</head>
+<body style="padding:20px;font-family: sans-serif">
+
+<h1 style="margin-top: 40px">htmx.js test suite</h1>
+<p id="version-number">Version:&nbsp;</p>
+
+<h2>Scratch Page</h2>
+<ul>
+    <li>
+        <a href="scratch/scratch.html">Scratch Page</a>
+    </li>
+</ul>
+
+<h2>Manual Tests</h2>
+<a href="manual">Here</a>
+
+<h2>Mocha Test Suite</h2>
+<a href="index.html">[ALL]</a>
+
+<script src="../node_modules/chai/chai.js"></script>
+<script src="../node_modules/chai-dom/chai-dom.js"></script>
+<script src="../node_modules/mocha/mocha.js"></script>
+<script src="../node_modules/sinon/pkg/sinon.js"></script>
+<script src="../node_modules/htmx.org/dist/htmx.js"></script>
+<script>
+  // Do not log all the events in headless mode (the log output is enormous)
+  if (navigator.webdriver) {
+    htmx.logAll = function () { }
+  }
+
+  // Add the version number to the top
+  document.getElementById('version-number').innerText += htmx.version
+</script>
+
+<script class="mocha-init">
+    mocha.setup('bdd');
+    mocha.checkLeaks();
+    window.should = window.chai.should()
+</script>
+
+<script src="./util.js"></script>
+<script src="../amz-content-sha256.js"></script>
+<script src="ext/test.js"></script>
+
+<div id="mocha"></div>
+
+<script class="mocha-exec">
+    document.addEventListener("DOMContentLoaded", function () {
+        mocha.run();
+    })
+</script>
+<em>Work Area</em>
+<hr/>
+<div id="work-area" hx-history-elt></div>
+</body>
+</html>

package/test/util.js

@@ -0,0 +1,115 @@
+/* Test Utilities */
+
+function byId(id) {
+  return document.getElementById(id);
+}
+
+function make(htmlStr) {
+  htmlStr = htmlStr.trim();
+  var makeFn = function () {
+    var range = document.createRange();
+    var fragment = range.createContextualFragment(htmlStr);
+    var wa = getWorkArea();
+    var child = null;
+    var children = fragment.children || fragment.childNodes; // IE
+    var appendedChildren = [];
+    while (children.length > 0) {
+      child = children[0];
+      wa.appendChild(child);
+      appendedChildren.push(child);
+    }
+    for (var i = 0; i < appendedChildren.length; i++) {
+      htmx.process(appendedChildren[i]);
+    }
+    return child; // return last added element
+  };
+  if (getWorkArea()) {
+    return makeFn();
+  } else {
+    ready(makeFn);
+  }
+}
+
+function ready(fn) {
+  if (document.readyState !== "loading") {
+    fn();
+  } else {
+    document.addEventListener("DOMContentLoaded", fn);
+  }
+}
+
+function getWorkArea() {
+  return byId("work-area");
+}
+
+function clearWorkArea() {
+  var workArea = getWorkArea();
+  if (workArea) workArea.innerHTML = "";
+}
+
+function removeWhiteSpace(str) {
+  return str.replace(/\s/g, "");
+}
+
+function getHTTPMethod(xhr) {
+  return xhr.requestHeaders["X-HTTP-Method-Override"] || xhr.method;
+}
+
+function makeServer() {
+  var server = sinon.fakeServer.create();
+  server.fakeHTTPMethods = true;
+  server.getHTTPMethod = function (xhr) {
+    return getHTTPMethod(xhr);
+  };
+  return server;
+}
+
+function parseParams(str) {
+  var re = /([^&=]+)=?([^&]*)/g;
+  var decode = function (str) {
+    return decodeURIComponent(str.replace(/\+/g, " "));
+  };
+  var params = {};
+  var e;
+  if (str) {
+    if (str.substr(0, 1) == "?") {
+      str = str.substr(1);
+    }
+    while ((e = re.exec(str))) {
+      var k = decode(e[1]);
+      var v = decode(e[2]);
+      if (params[k] !== undefined) {
+        if (!Array.isArray(params[k])) {
+          params[k] = [params[k]];
+        }
+        params[k].push(v);
+      } else {
+        params[k] = v;
+      }
+    }
+  }
+  return params;
+}
+
+function getQuery(url) {
+  var question = url.indexOf("?");
+  var hash = url.indexOf("#");
+  if (hash == -1 && question == -1) return "";
+  if (hash == -1) hash = url.length;
+  return question == -1 || hash == question + 1
+    ? url.substring(hash)
+    : url.substring(question + 1, hash);
+}
+
+function getParameters(xhr) {
+  if (getHTTPMethod(xhr) == "GET") {
+    return parseParams(getQuery(xhr.url));
+  } else {
+    return parseParams(xhr.requestBody);
+  }
+}
+
+function log(val) {
+  console.log(val);
+  return val;
+}