Add value_type= to core columns; HashedPassword replaces PasswordField

[davegaeddert]

Branches off plain-forms (#128). Base is plain-forms, so this diff also carries a merge of origin/master — plain-forms had not yet picked up #83, which this change is built on.

What this does

A core column constructor can now be handed a Python type it round-trips through:

password: Field[HashedPassword] = types.TextField(value_type=HashedPassword)

That lets a package or an app own a value's behavior without subclassing a field class — the one extension axis typed construction can support, because PEP 681 only honors field specifiers plain.postgres itself declares. plain-passwords is the first customer: PasswordField is deleted, and password becomes a required constructor argument for the first time. Under PasswordField, User(email=...) type-checked against a NOT NULL column — the one known hole #83 documented. That caveat is now gone from the docs because the hole is gone.

The protocol

class ValueType(Protocol):
    @classmethod
    def from_db(cls, raw: Any, /) -> Self: ...
    def to_db(self) -> Any: ...

Two methods, nothing else. Validation lives at whatever boundary constructs the value, not in the protocol — for a password that is the form field, the only place the raw input still exists.

What the hook guarantees

• Round trip. A read rebuilds the value after the column's own converter (so a JSON column decodes first, then builds); a write unwraps it.
• Refusal. Anything that isn't an instance of the declared type is a TypeError naming the field. One refusal in get_prep_value covers every path in: instance.update(), QuerySet.update(col="raw"), and filter(col="raw").
• Strict, symmetric descriptor. Field[X] both gets and sets an X. Assigning a primitive is a type error at the call site as well as a TypeError at write time. There is no lenient setter, so "is this already hashed?" can't be asked — today's pre_save format sniff and write-back cease to exist rather than moving.
• Invisible to migrations. The column is still text / jsonb, and value_type stays out of deconstruct(), so no migration file imports the type and changing one generates no migration.
• Typed as Field[X], not the text-field subtype, so text-only condition methods don't leak onto an opaque value. (When the typed query API lands — [1b] Add typed where() with field-method conditions #84 — a value-typed field's condition set comes from X, not from str.)
• Refused at the form boundary. model_field(Model.column) on a value-typed column raises rather than deriving a TextField that would hand the model a raw string.

plain-passwords

HashedPassword wraps the encoded hash: from_raw() hashes, check(raw) verifies, needs_rehash() reports a stale hasher, str() is the encoded hash, and repr() is deliberately opaque (<HashedPassword>) so a hash can't fall into a log line. validate_raw_password() — the three shipped rules, moved off the field — is what the new NewPasswordField form field runs before hashing.

---

Upgrade instructions

1. Model annotation

-from plain.passwords.types import PasswordField   # or plain.passwords.models
+from plain.passwords.values import HashedPassword

 @postgres.register_model
 class User(postgres.Model):
     email: Field[str] = types.EmailField()
-    password: Field[str] = PasswordField()
+    password: Field[HashedPassword] = types.TextField(value_type=HashedPassword)

plain.passwords.models and plain.passwords.types are deleted. There is no compatibility shim.

2. Migration files

Historical migrations reference PasswordField by import path and will fail to load. Rewrite each one to the plain text column it always was:

-import plain.passwords.models
-import plain.passwords.validators
-
-                (
-                    "password",
-                    plain.passwords.models.PasswordField(
-                        validators=[
-                            plain.passwords.validators.MinimumLengthValidator(),
-                            plain.passwords.validators.CommonPasswordValidator(),
-                            plain.passwords.validators.NumericPasswordValidator(),
-                        ]
-                    ),
-                ),
+                ("password", postgres.TextField()),

PasswordField.deconstruct() dropped its own max_length=128, so postgres.TextField() is the exact equivalent — the column definition is unchanged, no new migration is generated, and no data moves. (Writing max_length=128 here would generate a spurious AlterField, since the model no longer declares one.)

3. Writing a password

A raw string no longer hashes itself on save — it raises.

-user.password = raw_password
+user.password = HashedPassword.from_raw(raw_password)
 user.update()

-User.query.create(email=email, password=raw_password)
+User.query.create(email=email, password=HashedPassword.from_raw(raw_password))

Anywhere a password comes from user input, prefer routing it through the form layer (NewPasswordField) so the raw value is validated before it's hashed.

4. Reading a password

user.password is a HashedPassword, not a str. Anything that displays, serializes, or signs it needs the encoded form explicitly:

-signer.sign_object({"password": user.password})
+signer.sign_object({"password": str(user.password)})

Comparisons are better done with the value type than with strings:

-hmac.compare_digest(force_bytes(user.password), force_bytes(stored))
+user.password == HashedPassword(stored)      # constant-time via __eq__

-check_password(raw, user.password)
+user.password.check(raw)

5. Form fields

PasswordSetForm / PasswordChangeForm renamed new_password1 / new_password2 to new_password / confirm_password, matching the signup form's pairing. new_password cleans to a HashedPassword; confirm_password stays raw, because two hashes of the same password have different salts and can never be compared. Update any overridden templates.

6. Removed helpers

• get_password_errors(user, password, field=) — gone. The password form field validates the raw value itself, so the error attaches to the field automatically.
• set_user_password(user, password) now takes a HashedPassword, not a raw string.
• check_user_password(user, raw) is unchanged in signature and still rehashes on a stale hasher — it just uses HashedPassword.check() / .needs_rehash() to do it.