feat(types): enhance crypto column types and add TOTP/OTP storage (#758)

## Summary

Enhance the at-rest cryptographic column types and add two new types —
an encrypted TOTP shared-secret type and a hashed, self-expiring
one-time-code type.

## What changed

### `EncryptedString` / PGCrypto
- **Corrected `PGCryptoBackend`** to run encryption/decryption
server-side via SQLAlchemy `bind_expression`/`column_expression`: writes
wrap as `armor(pgp_sym_encrypt(:v, key))`, reads as
`pgp_sym_decrypt(dearmor(col), key)`. ASCII-armored ciphertext stays in
a `String` column, so the column type is unchanged. **Verified
interchangeable with `FernetBackend`** on PostgreSQL — same API, same
round-trip for value/None/empty/unicode, ciphertext at rest.
- Wired `cryptography` through the optionals facade
(`CRYPTOGRAPHY_INSTALLED`); `FernetBackend` raises
`MissingDependencyError` when it's absent. Importing
`advanced_alchemy.types` never eagerly imports the optional crypto
libraries — guards fire at construction time.
- **Deprecated the random default key**: constructing without an
explicit `key` now emits a `DeprecationWarning` (the random default
changes per process restart → undecryptable rows). Non-breaking.
- Cache the derived cipher for static keys; callable keys still
re-resolve.
- `__repr__` renders `type(self).__name__` so `EncryptedText`
reconstructs as `EncryptedText` (not `EncryptedString`) in autogenerated
migrations.

### `PasswordHash`
- Added `needs_rehash` to all three backends and
`HashedPassword.verify_and_update` for transparent rehash-on-login.
- Facade guards for argon2/passlib/pwdlib; default `length` 128 → 255;
narrowed `Argon2Hasher.verify` (no bare `except`).

### New types
- **`TOTPSecret`** — base32 TOTP secret encrypted at rest, returns a
pyotp-backed `TOTPProvider` (`now`/`verify`/`provisioning_uri`);
`generate_totp_secret` helper. `key` is required (no deprecated
default).
- **`OneTimeCode`** — a transient code hashed in a **JSON column that
also tracks expiry, single-use redemption, and wrong-guess lockout**, so
the whole lifecycle lives in one column:
- `OneTimeCode(backend, ttl_seconds=None, max_attempts=3)` stores
`{hash, expires_at, used_at, attempts}`.
- `HashedOneTimeCode` exposes `is_expired`/`is_used`/`is_locked`;
`verify` succeeds only while the code is redeemable; `redeem(code)`
verifies and returns the updated value to persist (marks used on
success, records a failed attempt otherwise).
- Single-use is always enforced; `max_attempts` (default 3) locks after
that many wrong guesses; `ttl_seconds` expires it. State persists by
assigning the redeemed value back and committing.
  - `generate_one_time_code(length=6, digits_only=True)` helper.
- Both new types are registered in the Alembic mako templates and
reconstruct faithfully.

### Docs & packaging
- New `cryptography` and `pyotp` optional-dependency extras.
- Usage docs for key management, PGCrypto requirements, password
hashing, TOTP, and the one-time-code redeem lifecycle; README feature
entries; a single changelog entry in the `1.11.0` block. All new docs
examples execute under Sybil.

## Backward compatibility
- No change to Fernet ciphertext format or key derivation.
- The default-key change is non-breaking (warning only).
- `compare_value`/`compare_expression` retained (documented as an
advanced extension point), not removed.

Author: cofin

.pre-commit-config.yaml

@@ -22,7 +22,7 @@ repos:
       - id: unasyncd
         additional_dependencies: ["ruff"]
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.15.14"
+    rev: "v0.15.15"
     hooks:
       # Run the linter.
       - id: ruff

README.md

@@ -47,7 +47,9 @@ offering:
 - Integrated support for UUID6 and UUID7 ([`uuid-utils`](https://github.com/aminalaee/uuid-utils) when installed, otherwise native in Python 3.14+, with UUID4 fallback on older versions).
 - Integrated support for Nano ID using [`fastnanoid`](https://github.com/oliverlambson/fastnanoid) (install with the `nanoid` extra)
 - Custom encrypted text type with multiple backend support including [`pgcrypto`](https://www.postgresql.org/docs/current/pgcrypto.html) for PostgreSQL and the Fernet implementation from [`cryptography`](https://cryptography.io/en/latest/) for other databases
-- Custom password hashing type with multiple backend support including [`Argon2`](https://github.com/P-H-C/phc-winner-argon2), [`Passlib`](https://passlib.readthedocs.io/en/stable/), and [`Pwdlib`](https://pwdlib.readthedocs.io/en/stable/) with automatic salt generation
+- Custom password hashing type with multiple backend support including [`Argon2`](https://github.com/P-H-C/phc-winner-argon2), [`Passlib`](https://passlib.readthedocs.io/en/stable/), and [`Pwdlib`](https://pwdlib.readthedocs.io/en/stable/) with automatic salt generation and rehash-on-verify for transparent hash upgrades on login
+- Custom TOTP shared-secret type that stores an authenticator seed encrypted at rest and verifies time-based one-time passwords via [`pyotp`](https://github.com/pyauth/pyotp) (install with the `pyotp` extra)
+- Custom one-time-code type that stores email/SMS verification codes hashed in JSON with built-in expiry, single-use redemption, attempt lockout, and a secure code generator
 - Pre-configured base classes with audit columns UUID or Big Integer primary keys and
   a [sentinel column](https://docs.sqlalchemy.org/en/20/core/connections.html#configuring-sentinel-columns).
 - Synchronous and asynchronous repositories featuring:

advanced_alchemy/_typing.py

@@ -25,13 +25,18 @@
 # ---------------------------------------------------------------------------
 # Feature-detection flags (use ``find_spec`` to avoid eagerly importing).
 # ---------------------------------------------------------------------------
+ARGON2_INSTALLED = find_spec("argon2") is not None
 ATTRS_INSTALLED = find_spec("attrs") is not None
 CATTRS_INSTALLED = find_spec("cattrs") is not None
+CRYPTOGRAPHY_INSTALLED = find_spec("cryptography") is not None
 LITESTAR_INSTALLED = find_spec("litestar") is not None
 MSGSPEC_INSTALLED = find_spec("msgspec") is not None
 NUMPY_INSTALLED = find_spec("numpy") is not None
 ORJSON_INSTALLED = find_spec("orjson") is not None
+PASSLIB_INSTALLED = find_spec("passlib") is not None
+PWDLIB_INSTALLED = find_spec("pwdlib") is not None
 PYDANTIC_INSTALLED = find_spec("pydantic") is not None
+PYOTP_INSTALLED = find_spec("pyotp") is not None
 SQLMODEL_INSTALLED = find_spec("sqlmodel") is not None
 
 
@@ -375,14 +380,19 @@ class EmptyEnum(enum.Enum):
 
 
 __all__ = (
+    "ARGON2_INSTALLED",
     "ATTRS_INSTALLED",
     "ATTRS_NOTHING_STUB",
     "CATTRS_INSTALLED",
+    "CRYPTOGRAPHY_INSTALLED",
     "LITESTAR_INSTALLED",
     "MSGSPEC_INSTALLED",
     "NUMPY_INSTALLED",
     "ORJSON_INSTALLED",
+    "PASSLIB_INSTALLED",
+    "PWDLIB_INSTALLED",
     "PYDANTIC_INSTALLED",
+    "PYOTP_INSTALLED",
     "SQLMODEL_INSTALLED",
     "UNSET",
     "UNSET_STUB",

advanced_alchemy/alembic/templates/asyncio/script.py.mako

@@ -7,31 +7,22 @@ Create Date: ${create_date}
 """
 
 import warnings
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 import sqlalchemy as sa
 from alembic import op
-from advanced_alchemy.types import Bool, EncryptedString, EncryptedText, GUID, JsonB, ORA_JSONB, DateTimeUTC, StoredObject, PasswordHash, FernetBackend
+from advanced_alchemy.types import Bool, EncryptedString, EncryptedText, GUID, JsonB, ORA_JSONB, DateTimeUTC, StoredObject, PasswordHash, FernetBackend, TOTPSecret, OneTimeCode
 from advanced_alchemy.types.encrypted_string import PGCryptoBackend
+from advanced_alchemy.types.password_hash.argon2 import Argon2Hasher
+from advanced_alchemy.types.password_hash.passlib import PasslibHasher
+from advanced_alchemy.types.password_hash.pwdlib import PwdlibHasher
 from sqlalchemy import Text  # noqa: F401
 ${imports if imports else ""}
-try:
-    from advanced_alchemy.types.password_hash.argon2 import Argon2Hasher
-except ImportError:
-    Argon2Hasher = Any  # type: ignore
-try:
-    from advanced_alchemy.types.password_hash.passlib import PasslibHasher
-except ImportError:
-    PasslibHasher = Any  # type: ignore
-try:
-    from advanced_alchemy.types.password_hash.pwdlib import PwdlibHasher
-except ImportError:
-    PwdlibHasher = Any  # type: ignore
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
-__all__ = ["downgrade", "upgrade", "schema_upgrades", "schema_downgrades", "data_upgrades", "data_downgrades"]
+__all__ = ("downgrade", "upgrade", "schema_upgrades", "schema_downgrades", "data_upgrades", "data_downgrades")
 
 sa.GUID = GUID
 sa.Bool = Bool
@@ -47,6 +38,8 @@ sa.PasslibHasher = PasslibHasher
 sa.PwdlibHasher = PwdlibHasher
 sa.FernetBackend = FernetBackend
 sa.PGCryptoBackend = PGCryptoBackend
+sa.TOTPSecret = TOTPSecret
+sa.OneTimeCode = OneTimeCode
 
 # revision identifiers, used by Alembic.
 revision = ${repr(up_revision)}

advanced_alchemy/alembic/templates/sync/script.py.mako

@@ -7,31 +7,22 @@ Create Date: ${create_date}
 """
 
 import warnings
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 import sqlalchemy as sa
 from alembic import op
-from advanced_alchemy.types import Bool, EncryptedString, EncryptedText, GUID, JsonB, ORA_JSONB, DateTimeUTC, StoredObject, PasswordHash, FernetBackend
+from advanced_alchemy.types import Bool, EncryptedString, EncryptedText, GUID, JsonB, ORA_JSONB, DateTimeUTC, StoredObject, PasswordHash, FernetBackend, TOTPSecret, OneTimeCode
 from advanced_alchemy.types.encrypted_string import PGCryptoBackend
+from advanced_alchemy.types.password_hash.argon2 import Argon2Hasher
+from advanced_alchemy.types.password_hash.passlib import PasslibHasher
+from advanced_alchemy.types.password_hash.pwdlib import PwdlibHasher
 from sqlalchemy import Text  # noqa: F401
 ${imports if imports else ""}
-try:
-    from advanced_alchemy.types.password_hash.argon2 import Argon2Hasher
-except ImportError:
-    Argon2Hasher = Any  # type: ignore
-try:
-    from advanced_alchemy.types.password_hash.passlib import PasslibHasher
-except ImportError:
-    PasslibHasher = Any  # type: ignore
-try:
-    from advanced_alchemy.types.password_hash.pwdlib import PwdlibHasher
-except ImportError:
-    PwdlibHasher = Any  # type: ignore
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
-__all__ = ["downgrade", "upgrade", "schema_upgrades", "schema_downgrades", "data_upgrades", "data_downgrades"]
+__all__ = ("downgrade", "upgrade", "schema_upgrades", "schema_downgrades", "data_upgrades", "data_downgrades")
 
 sa.GUID = GUID
 sa.Bool = Bool
@@ -47,6 +38,8 @@ sa.PasslibHasher = PasslibHasher
 sa.PwdlibHasher = PwdlibHasher
 sa.FernetBackend = FernetBackend
 sa.PGCryptoBackend = PGCryptoBackend
+sa.TOTPSecret = TOTPSecret
+sa.OneTimeCode = OneTimeCode
 
 # revision identifiers, used by Alembic.
 revision = ${repr(up_revision)}

advanced_alchemy/types/__init__.py

@@ -1,6 +1,6 @@
 """SQLAlchemy custom types for use with the ORM."""
 
-from advanced_alchemy.types import encrypted_string, file_object, password_hash
+from advanced_alchemy.types import encrypted_string, file_object, password_hash, totp
 from advanced_alchemy.types.boolean import Bool
 from advanced_alchemy.types.datetime import DateTimeUTC
 from advanced_alchemy.types.encrypted_string import (
@@ -23,6 +23,12 @@
 from advanced_alchemy.types.json import ORA_JSONB, JsonB
 from advanced_alchemy.types.mutables import MutableList
 from advanced_alchemy.types.password_hash.base import HashedPassword, PasswordHash
+from advanced_alchemy.types.password_hash.one_time_code import (
+    HashedOneTimeCode,
+    OneTimeCode,
+    generate_one_time_code,
+)
+from advanced_alchemy.types.totp import TOTPProvider, TOTPSecret, generate_totp_secret
 from advanced_alchemy.types.vector import Vector
 
 __all__ = (
@@ -39,17 +45,24 @@
     "FernetBackend",
     "FileObject",
     "FileObjectList",
+    "HashedOneTimeCode",
     "HashedPassword",
     "JsonB",
     "MutableList",
+    "OneTimeCode",
     "PasswordHash",
     "StorageBackend",
     "StorageBackendT",
     "StorageRegistry",
     "StoredObject",
+    "TOTPProvider",
+    "TOTPSecret",
     "Vector",
     "encrypted_string",
     "file_object",
+    "generate_one_time_code",
+    "generate_totp_secret",
     "password_hash",
     "storages",
+    "totp",
 )