From 6ef9dd676cb0a6b63e128e9466abdb7706b6574a Mon Sep 17 00:00:00 2001
From: Michael Novotny <manovotny@gmail.com>
Date: Wed, 28 Oct 2026 17:42:50 -0500
Subject: [PATCH 1/3] docs(backend): correct the salted password digest order
 in createUser() JSDoc

The Backend API reads `md5_salted` and `sha256_salted` digests as `hash$salt`, so the JSDoc now says that instead of `salt$hash`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/fix-salted-password-digest-order.md | 5 +++++
 packages/backend/src/api/endpoints/UserApi.ts  | 8 ++++----
 2 files changed, 9 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/fix-salted-password-digest-order.md

diff --git a/.changeset/fix-salted-password-digest-order.md b/.changeset/fix-salted-password-digest-order.md
new file mode 100644
index 00000000000..1420e590750
--- /dev/null
+++ b/.changeset/fix-salted-password-digest-order.md
@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Fix the `md5_salted` and `sha256_salted` entries in the `createUser()` JSDoc to show the `password_digest` format the Backend API expects: `hash$salt`, not `salt$hash`.
diff --git a/packages/backend/src/api/endpoints/UserApi.ts b/packages/backend/src/api/endpoints/UserApi.ts
index b41d36ec020..54b77f6921e 100644
--- a/packages/backend/src/api/endpoints/UserApi.ts
+++ b/packages/backend/src/api/endpoints/UserApi.ts
@@ -145,9 +145,9 @@ export type UserPasswordHashingParams = {
    *   </ul>
    *  <li> [`md5_salted` (insecure)](https://en.wikipedia.org/wiki/MD5) </li>
    *   <ul>
-   *    <li> When set, `password_digest` must be in the format of `salt$hash`. </li>
-   *    <li> _salt:_ The salt used to generate the above hash. </li>
+   *    <li> When set, `password_digest` must be in the format of `hash$salt`. </li>
    *    <li> _hash:_ A 32-length hex string. </li>
+   *    <li> _salt:_ The salt used to generate the above hash. </li>
    *   </ul>
    *  <li> [`pbkdf2_sha1`](https://en.wikipedia.org/wiki/PBKDF2) </li>
    *   <ul>
@@ -205,9 +205,9 @@ export type UserPasswordHashingParams = {
    *   </ul>
    *  <li> [`sha256_salted` (insecure)](https://en.wikipedia.org/wiki/SHA-2) </li>
    *   <ul>
-   *    <li> When set, `password_digest` must be in the format of `salt$hash`. </li>
-   *    <li> _salt:_ The salt used to generate the above hash. </li>
+   *    <li> When set, `password_digest` must be in the format of `hash$salt`. </li>
    *    <li> _hash:_ A 64-length hex string. </li>
+   *    <li> _salt:_ The salt used to generate the above hash. </li>
    *   </ul>
    *  <li> [`argon2`](https://argon2.online/) variants: `argon2i` and `argon2id`. </li>
    *   <ul>

From 9d535e968b066c9795ba1940cde6ca96a42da4e6 Mon Sep 17 00:00:00 2001
From: Michael Novotny <manovotny@gmail.com>
Date: Wed, 28 Oct 2026 17:47:37 -0500
Subject: [PATCH 2/3] docs(backend): describe the digest fix for people
 upgrading

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/fix-salted-password-digest-order.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.changeset/fix-salted-password-digest-order.md b/.changeset/fix-salted-password-digest-order.md
index 1420e590750..5bf740cb888 100644
--- a/.changeset/fix-salted-password-digest-order.md
+++ b/.changeset/fix-salted-password-digest-order.md
@@ -2,4 +2,4 @@
 '@clerk/backend': patch
 ---
 
-Fix the `md5_salted` and `sha256_salted` entries in the `createUser()` JSDoc to show the `password_digest` format the Backend API expects: `hash$salt`, not `salt$hash`.
+The `createUser()` JSDoc now shows the `password_digest` format the Backend API accepts for `md5_salted` and `sha256_salted`: `hash$salt`, not `salt$hash`.

From 9f1148ddf3ebdd7080bc45b010b04ff367f5478e Mon Sep 17 00:00:00 2001
From: Michael Novotny <manovotny@gmail.com>
Date: Wed, 28 Oct 2026 19:18:54 -0500
Subject: [PATCH 3/3] fix(backend): accept every documented hasher in
 PasswordHasher

The createUser() JSDoc documents six hashers the type rejected, including `md5_salted` and `sha256_salted`, so TypeScript callers needed a cast to use them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/fix-salted-password-digest-order.md | 2 +-
 packages/backend/src/api/endpoints/UserApi.ts  | 6 ++++++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/.changeset/fix-salted-password-digest-order.md b/.changeset/fix-salted-password-digest-order.md
index 5bf740cb888..fc857117659 100644
--- a/.changeset/fix-salted-password-digest-order.md
+++ b/.changeset/fix-salted-password-digest-order.md
@@ -2,4 +2,4 @@
 '@clerk/backend': patch
 ---
 
-The `createUser()` JSDoc now shows the `password_digest` format the Backend API accepts for `md5_salted` and `sha256_salted`: `hash$salt`, not `salt$hash`.
+Add `bcrypt_peppered`, `md5_salted`, `pbkdf2_sha512`, `pbkdf2_sha512_hex`, `sha256_salted`, and `sha512_symfony` to the `PasswordHasher` type, so TypeScript accepts every hasher the `createUser()` JSDoc documents. The JSDoc for `md5_salted` and `sha256_salted` now also shows the `password_digest` format the Backend API accepts: `hash$salt`, not `salt$hash`.
diff --git a/packages/backend/src/api/endpoints/UserApi.ts b/packages/backend/src/api/endpoints/UserApi.ts
index 54b77f6921e..78b65d2c3e1 100644
--- a/packages/backend/src/api/endpoints/UserApi.ts
+++ b/packages/backend/src/api/endpoints/UserApi.ts
@@ -101,15 +101,21 @@ export type PasswordHasher =
   | 'argon2id'
   | 'awscognito'
   | 'bcrypt'
+  | 'bcrypt_peppered'
   | 'bcrypt_sha256_django'
   | 'md5'
+  | 'md5_salted'
   | 'pbkdf2_sha256'
   | 'pbkdf2_sha256_django'
   | 'pbkdf2_sha1'
+  | 'pbkdf2_sha512'
+  | 'pbkdf2_sha512_hex'
   | 'phpass'
   | 'scrypt_firebase'
   | 'scrypt_werkzeug'
   | 'sha256'
+  | 'sha256_salted'
+  | 'sha512_symfony'
   | 'md5_phpass'
   | 'ldap_ssha';