perf(accounts): use lower-cost Argon2 for UserCode PINs

ljmerza · ljmerza · commit 260f96f35e77 · 2026-05-01T20:44:41.000-04:00
Alarm PINs are 4-8 digits with a 10K-100M keyspace. Stretching them at the default user-password Argon2 cost (~150-300ms/verify) doesn't materially raise an offline-brute-force attacker's bar - the keyspace is so small that the entire space is recovered in minutes-to-hours even at strong cost - while the slow verify shows up as a multi- hundred-ms tax on every arm/disarm round trip from the HA MQTT alarm panel. Add UserCodeArgon2Hasher (algorithm "argon2-pin", time_cost=1, memory_cost=8 MiB, parallelism=2; ~30ms/verify) and route create_user_code / update_user_code through it. User passwords keep the strong default. Existing UserCode rows hashed under the original "argon2" algorithm continue to verify on the strong hasher with no migration required - check_password resolves by hash prefix. Combined with the PR #46 MQTT-template fix, this gets HA-driven arm/ disarm clicks down from ~2s to subsecond round-trip on the live home-lab broker.
diff --git a/backend/accounts/hashers.py b/backend/accounts/hashers.py
@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from django.contrib.auth.hashers import Argon2PasswordHasher
+
+
+class UserCodeArgon2Hasher(Argon2PasswordHasher):
+    """
+    Lower-cost Argon2 hasher for UserCode PINs.
+
+    Alarm PINs are 4-8 digits with a 10K-100M keyspace. Stretching them with
+    the default user-password Argon2 cost (~150-300ms/verify) doesn't
+    materially raise an offline-brute-force attacker's cost: the keyspace is
+    so small that the entire space is recovered in minutes-to-hours even at
+    strong cost, while the slow verify shows up as a multi-hundred-ms tax on
+    every arm/disarm round trip through the MQTT alarm panel.
+
+    Calibrated for ~30ms/verify - plenty for the online-rate-limited entry
+    path while letting clicks feel instant. The algorithm discriminator is
+    renamed so check_password routes new and old UserCode hashes to the right
+    hasher: existing rows hashed under the default 'argon2' algorithm continue
+    to verify on the strong hasher with no migration required.
+
+    Strong-cost protection for User passwords (long, high-entropy, large
+    keyspace) is unchanged - this hasher is only routed through explicit
+    `make_password(..., hasher='argon2-pin')` calls in `accounts.use_cases.user_codes`.
+    """
+
+    algorithm = "argon2-pin"
+    time_cost = 1
+    memory_cost = 8 * 1024
+    parallelism = 2
diff --git a/backend/accounts/tests/test_user_codes_hasher.py b/backend/accounts/tests/test_user_codes_hasher.py
@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from datetime import datetime
+from datetime import timezone as dt_timezone
+
+from django.contrib.auth.hashers import check_password, get_hasher, make_password
+from django.test import TestCase
+
+from accounts.hashers import UserCodeArgon2Hasher
+from accounts.models import User, UserCode
+from accounts.use_cases import code_validation
+from accounts.use_cases.user_codes import create_user_code, update_user_code
+
+
+class UserCodeArgon2HasherRegistrationTests(TestCase):
+    def test_hasher_is_registered_under_argon2_pin_algorithm(self):
+        hasher = get_hasher("argon2-pin")
+        self.assertIsInstance(hasher, UserCodeArgon2Hasher)
+
+    def test_reduced_cost_params(self):
+        hasher = get_hasher("argon2-pin")
+        self.assertEqual(hasher.time_cost, 1)
+        self.assertEqual(hasher.memory_cost, 8 * 1024)
+        self.assertEqual(hasher.parallelism, 2)
+
+
+class UserCodeHasherUsageTests(TestCase):
+    def setUp(self):
+        self.user = User.objects.create_user(email="hasher@example.com", password="pass")
+
+    def test_create_user_code_routes_through_argon2_pin(self):
+        code = create_user_code(user=self.user, raw_code="1234", label="kitchen")
+        self.assertTrue(
+            code.code_hash.startswith("argon2-pin$"),
+            f"expected argon2-pin$ prefix, got: {code.code_hash[:30]}",
+        )
+
+    def test_update_user_code_rotates_to_argon2_pin(self):
+        code = create_user_code(user=self.user, raw_code="1234")
+        original_hash = code.code_hash
+        update_user_code(code=code, changes={"code": "5678"})
+        code.refresh_from_db()
+        self.assertNotEqual(code.code_hash, original_hash)
+        self.assertTrue(code.code_hash.startswith("argon2-pin$"))
+
+    def test_check_password_round_trips_new_hash(self):
+        hashed = make_password("4242", hasher="argon2-pin")
+        self.assertTrue(hashed.startswith("argon2-pin$"))
+        self.assertTrue(check_password("4242", hashed))
+        self.assertFalse(check_password("0000", hashed))
+
+    def test_validates_new_argon2_pin_code_via_use_case(self):
+        code = create_user_code(user=self.user, raw_code="9876")
+        now = datetime(2025, 1, 1, 12, 0, tzinfo=dt_timezone.utc)
+        result = code_validation.validate_user_code(user=self.user, raw_code="9876", now=now)
+        self.assertEqual(result.code.id, code.id)
+
+    def test_legacy_argon2_hash_still_verifies(self):
+        # Existing rows in production were hashed under the default 'argon2'
+        # algorithm. Verify those continue to validate after the new hasher
+        # is added - no migration required.
+        legacy_hash = make_password("1234")
+        self.assertTrue(legacy_hash.startswith("argon2$"))
+        UserCode.objects.create(
+            user=self.user,
+            code_hash=legacy_hash,
+            label="legacy",
+            code_type=UserCode.CodeType.PERMANENT,
+            pin_length=4,
+            is_active=True,
+        )
+        now = datetime(2025, 1, 1, 12, 0, tzinfo=dt_timezone.utc)
+        result = code_validation.validate_user_code(user=self.user, raw_code="1234", now=now)
+        self.assertTrue(result.code.code_hash.startswith("argon2$"))
diff --git a/backend/accounts/use_cases/user_codes.py b/backend/accounts/use_cases/user_codes.py
@@ -30,7 +30,7 @@ def create_user_code(
     raw_code = (raw_code or "").strip()
     code = UserCode.objects.create(
         user=user,
-        code_hash=make_password(raw_code),
+        code_hash=make_password(raw_code, hasher="argon2-pin"),
         label=label or "",
         code_type=code_type,
         pin_length=len(raw_code),
@@ -57,7 +57,7 @@ def update_user_code(
     """Update a user code and its allowed states."""
     if "code" in changes and changes.get("code"):
         raw_code = str(changes.get("code") or "").strip()
-        code.code_hash = make_password(raw_code)
+        code.code_hash = make_password(raw_code, hasher="argon2-pin")
         code.pin_length = len(raw_code)
 
     if "label" in changes:
diff --git a/backend/config/settings.py b/backend/config/settings.py
@@ -110,6 +110,7 @@
 
 PASSWORD_HASHERS = [
     "django.contrib.auth.hashers.Argon2PasswordHasher",
+    "accounts.hashers.UserCodeArgon2Hasher",
     "django.contrib.auth.hashers.PBKDF2PasswordHasher",
     "django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher",
     "django.contrib.auth.hashers.BCryptSHA256PasswordHasher",
