Security and File Storage Types#
Advanced Alchemy includes column types for symmetric field encryption, password hashing, TOTP seeds, one-time verification codes, and transaction-synchronized object storage.
Encrypted Text and Password Hashing#
Use EncryptedString or EncryptedText when your app needs to decrypt a secret later (like an API token), and PasswordHash when storing one-way user passwords:
from sqlalchemy.orm import Mapped, mapped_column
from advanced_alchemy.base import BigIntBase
from advanced_alchemy.types import EncryptedString, EncryptedText
class SecretRecord(BigIntBase):
__tablename__ = "secret_record"
api_token: Mapped[str] = mapped_column(EncryptedString(key="my-secret-key"))
private_notes: Mapped[str] = mapped_column(EncryptedText(key="my-secret-key"))
from sqlalchemy.orm import Mapped, mapped_column
from advanced_alchemy.base import BigIntBase
from advanced_alchemy.types import HashedPassword, PasswordHash
from advanced_alchemy.types.password_hash.argon2 import Argon2Hasher
hasher = Argon2Hasher()
class AccountRecord(BigIntBase):
__tablename__ = "account_record"
password: Mapped[str] = mapped_column(PasswordHash(backend=hasher))
stored = HashedPassword(hasher.hash("s3cret-passphrase"), hasher)
verified, _ = stored.verify_and_update("s3cret-passphrase")
assert verified is True
Two-Factor Secrets and One-Time Codes#
For multi-factor login flows, TOTPSecret encrypts authenticator app seeds (Google Authenticator, 1Password), while OneTimeCode hashes short-lived email or SMS verification codes and tracks retry limits:
from sqlalchemy.orm import Mapped, mapped_column
from advanced_alchemy.base import BigIntBase
from advanced_alchemy.types import TOTPProvider, TOTPSecret, generate_totp_secret
class MfaEnrollment(BigIntBase):
__tablename__ = "mfa_enrollment"
seed: Mapped[str] = mapped_column(TOTPSecret(key="my-secret-key", issuer="ACME"))
provider = TOTPProvider(generate_totp_secret(), issuer="ACME")
uri = provider.provisioning_uri(name="alice@example.com")
assert uri.startswith("otpauth://totp/")
from typing import Any
from sqlalchemy.orm import Mapped, mapped_column
from advanced_alchemy.base import BigIntBase
from advanced_alchemy.types import HashedOneTimeCode, OneTimeCode, generate_one_time_code
from advanced_alchemy.types.password_hash.argon2 import Argon2Hasher
otp_hasher = Argon2Hasher()
class LoginCode(BigIntBase):
__tablename__ = "login_code"
code: Mapped[Any] = mapped_column(
OneTimeCode(backend=otp_hasher, ttl_seconds=600, max_attempts=3),
)
raw_code = generate_one_time_code()
otp = HashedOneTimeCode(otp_hasher.hash(raw_code), otp_hasher, max_attempts=3)
ok, otp = otp.redeem(raw_code)
assert ok is True and otp.is_used is True
File and Object Storage#
Instead of storing binary payloads inside SQL columns, StoredObject persists file metadata in the table and writes object bytes to local disk, S3, Google Cloud Storage, or Azure Blob Storage through storages:
from pathlib import Path
import tempfile
from typing import Optional
from sqlalchemy.orm import Mapped, mapped_column
from advanced_alchemy.base import UUIDBase
from advanced_alchemy.types import FileObject, FileObjectList, StoredObject, storages
tmp_storage = tempfile.mkdtemp()
storages.register_backend(f"file://{Path(tmp_storage)}", key="documents")
class DocumentRecord(UUIDBase):
__tablename__ = "document_record"
attachment: Mapped[Optional[FileObject]] = mapped_column(
StoredObject(backend="documents"),
nullable=True,
)
images: Mapped[Optional[FileObjectList]] = mapped_column(
StoredObject(backend="documents", multiple=True),
nullable=True,
)
file_obj = FileObject(backend="documents", filename="report.txt", metadata={"category": "report"})
file_obj.update_metadata({"priority": "high"})
storages.clear_backends()
from pathlib import Path
import tempfile
from sqlalchemy.orm import Mapped, mapped_column
from advanced_alchemy.base import UUIDBase
from advanced_alchemy.types import FileObject, FileObjectList, StoredObject, storages
tmp_storage = tempfile.mkdtemp()
storages.register_backend(f"file://{Path(tmp_storage)}", key="documents")
class DocumentRecord(UUIDBase):
__tablename__ = "document_record"
attachment: Mapped[FileObject | None] = mapped_column(
StoredObject(backend="documents"),
nullable=True,
)
images: Mapped[FileObjectList | None] = mapped_column(
StoredObject(backend="documents", multiple=True),
nullable=True,
)
file_obj = FileObject(backend="documents", filename="report.txt", metadata={"category": "report"})
file_obj.update_metadata({"priority": "high"})
storages.clear_backends()
See Litestar File and Object Storage and FastAPI File Storage and Multi-Binds for complete file-upload web examples.