From 91c21fbb4b1e5d80b22ac5fd62c5a3ae0852605b Mon Sep 17 00:00:00 2001
From: Xe Iaso <me@xeiaso.net>
Date: Fri, 16 May 2025 12:37:39 -0400
Subject: [PATCH] docs: add HTMX workaround (#511)

* docs: add HTMX workaround

Signed-off-by: Xe Iaso <me@xeiaso.net>

* chore: spelling

Signed-off-by: Xe Iaso <me@xeiaso.net>

---------

Signed-off-by: Xe Iaso <me@xeiaso.net>
---
 .github/actions/spelling/expect.txt        |  2 +
 docs/docs/admin/frameworks/_category_.json |  8 ++++
 docs/docs/admin/frameworks/htmx.mdx        | 45 ++++++++++++++++++++++
 3 files changed, 55 insertions(+)
 create mode 100644 docs/docs/admin/frameworks/_category_.json
 create mode 100644 docs/docs/admin/frameworks/htmx.mdx

diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt
index 66f460b..e1e3065 100644
--- a/.github/actions/spelling/expect.txt
+++ b/.github/actions/spelling/expect.txt
@@ -87,7 +87,9 @@ healthcheck
 hec
 hmc
 hostable
+htmx
 httpdebug
+hypertext
 iat
 ifm
 inp
diff --git a/docs/docs/admin/frameworks/_category_.json b/docs/docs/admin/frameworks/_category_.json
new file mode 100644
index 0000000..28eefe8
--- /dev/null
+++ b/docs/docs/admin/frameworks/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "Frameworks",
+  "position": 30,
+  "link": {
+    "type": "generated-index",
+    "description": "Information about getting specific frameworks or tools working with Anubis."
+  }
+}
\ No newline at end of file
diff --git a/docs/docs/admin/frameworks/htmx.mdx b/docs/docs/admin/frameworks/htmx.mdx
new file mode 100644
index 0000000..2b2ea49
--- /dev/null
+++ b/docs/docs/admin/frameworks/htmx.mdx
@@ -0,0 +1,45 @@
+# HTMX
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+[HTMX](https://htmx.org) is a framework that enables you to write applications using hypertext as the engine of application state. This enables you to simplify you server side code by having it return HTML instead of JSON. This can interfere with Anubis because Anubis challenge pages also return HTML.
+
+To work around this, you can make a custom [expression](../configuration/expressions.mdx) rule that allows HTMX requests if the user has passed a challenge in the past:
+
+<Tabs>
+<TabItem value="json" label="JSON">
+
+```json
+{
+  "name": "allow-htmx-iff-already-passed-challenge",
+  "action": "ALLOW",
+  "expression": {
+    "all": [
+      "\"Cookie\" in headers",
+      "headers[\"Cookie\"].contains(\"anubis-auth\")",
+      "\"Hx-Request\" in headers",
+      "headers[\"Hx-Request\"] == \"true\""
+    ]
+  }
+}
+```
+
+</TabItem>
+<TabItem value="yaml" label="YAML" default>
+
+```yaml
+- name: allow-htmx-iff-already-passed-challenge
+  action: ALLOW
+  expression:
+    all:
+      - '"Cookie" in headers'
+      - 'headers["Cookie"].contains("anubis-auth")'
+      - '"Hx-Request" in headers'
+      - 'headers["Hx-Request"] == "true"'
+```
+
+</TabItem>
+</Tabs>
+
+This will reduce some security because it does not assert the validity of the Anubis auth cookie, however in trade it improves the experience for existing users.