change: use RFC 9535 syntax for jwt-role-claim-key config

BREAKING CHANGE

Breaks the string comparison operators implemented in #3813. Those can
be replaced with regex searches using JSON Path `search()` function.

Signed-off-by: Taimoor Zaeem <taimoorzaeem@gmail.com>

docs/postgrest.dict

@@ -30,7 +30,6 @@ CSV
 durations
 DDL
 DOM
-DSL
 DevOps
 Dramatiq
 dockerize
@@ -76,7 +75,6 @@ isdistinct
 JS
 js
 JSON
-JSPath
 JWK
 JWT
 jwt

docs/references/auth.rst

@@ -224,40 +224,31 @@ It's recommended to leave the JWT cache enabled as our load tests indicate ~20%
 JWT Role Extraction
 -------------------
 
-A JSPath DSL that specifies the location of the :code:`role` key in the JWT claims. It's configured by :ref:`jwt-role-claim-key`. This can be used to consume a JWT provided by a third party service like Auth0, Okta, Microsoft Entra or Keycloak.
+A JSON Path (`RFC 9535 <https://www.rfc-editor.org/rfc/rfc9535.html>`_) can be specified for the location of the :code:`role` key in the JWT claims. It's configured by :ref:`jwt-role-claim-key`. This can be used to consume a JWT provided by a third party service like Auth0, Okta, Microsoft Entra or Keycloak.
 
-The DSL follows the `JSONPath <https://goessner.net/articles/JsonPath/>`_ expression grammar with extended string comparison operators. Supported operators are:
-
-- ``==`` selects the first array element that exactly matches the right operand
-- ``!=`` selects the first array element that does not match the right operand
-- ``^==`` selects the first array element that starts with the right operand
-- ``==^`` selects the first array element that ends with the right operand
-- ``*==`` selects the first array element that contains the right operand
+You can quickly try out JSON Path by visiting https://serdejsonpath.live.
 
 Usage examples:
 
   .. code:: bash
 
     # {"postgrest":{"roles": ["other", "author"]}}
-    # the DSL accepts characters that are alphanumerical or one of "_$@" as keys
-    jwt-role-claim-key = ".postgrest.roles[1]"
+    jwt-role-claim-key = "$$.postgrest.roles[1]"
 
     # {"https://www.example.com/role": { "key": "author" }}
-    # non-alphanumerical characters can go inside quotes(escaped in the config value)
-    jwt-role-claim-key = ".\"https://www.example.com/role\".key"
+    # non-alphanumerical characters can go inside single quotes
+    jwt-role-claim-key = "$$['https://www.example.com/role'].key"
 
     # {"postgrest":{"roles": ["other", "author"]}}
-    # `@` represents the current element in the array
-    # all the these match the string "author"
-    jwt-role-claim-key = ".postgrest.roles[?(@ == \"author\")]"
-    jwt-role-claim-key = ".postgrest.roles[?(@ != \"other\")]"
-    jwt-role-claim-key = ".postgrest.roles[?(@ ^== \"aut\")]"
-    jwt-role-claim-key = ".postgrest.roles[?(@ ==^ \"hor\")]"
-    jwt-role-claim-key = ".postgrest.roles[?(@ *== \"utho\")]"
+    # filter based on equality or regular expression
+    jwt-role-claim-key = "$$.postgrest.roles[?(@ == 'author')]"
+    jwt-role-claim-key = "$$.postgrest.roles[?search(@, '^au')]"
 
 .. note::
 
-  The string comparison operators are implemented as a custom extension to the JSPath and does not strictly follow the `RFC 9535 <https://www.rfc-editor.org/rfc/rfc9535.html>`_.
+  - If JSON Path query returns multiple values, the first one gets selected.
+  - Only when using the :ref:`file_config`, all ``$`` characters in the value must be escaped with an additional ``$`` char. For :ref:`env_variables_config` and :ref:`in_db_config`, only use a single ``$`` char.
+  - In our implementation, only the `search()` function from `JSON Path Functions <https://www.rfc-editor.org/rfc/rfc9535.html#name-function-extensions>`_ is available for filtering.
 
 JWT Security
 ------------

docs/references/configuration.rst

@@ -694,7 +694,7 @@ jwt-role-claim-key
 
   =============== =================================
   **Type**        String
-  **Default**     .role
+  **Default**     $.role
   **Reloadable**  Y
   **Environment** PGRST_JWT_ROLE_CLAIM_KEY
   **In-Database** pgrst.jwt_role_claim_key
@@ -704,6 +704,10 @@ jwt-role-claim-key
 
   See :ref:`jwt_role_extract` on how to specify key paths and usage examples.
 
+.. warning::
+
+  Only when using :ref:`file_config`, the ``$`` char needs to be escaped, so use ``$$`` and PostgREST will interpret it as a single ``$`` character.
+
 .. _jwt-secret:
 
 jwt-secret