py-app-runner 0.5.49.dev0__py3-none-any.whl

py_app_runner/crypto/commands.py

@@ -0,0 +1,164 @@
+"""Command implementations, importable directly for programmatic use.
+
+Each takes its collaborators explicitly and returns a process exit code rather than
+printing and exiting, so the whole surface is testable without capturing stdout.
+"""
+
+import re
+from collections.abc import Callable
+
+import psycopg
+from psycopg import sql
+
+from py_app_runner.crypto.errors import CryptoError
+from py_app_runner.crypto.fields import FieldCrypto, generate_key, key_id_of
+
+Out = Callable[[str], None]
+
+# The table and column reach SQL as identifiers, which cannot be bound as parameters. They
+# go through psycopg's Identifier for quoting, but are whitelisted first: Identifier will
+# happily quote `people; DROP TABLE people` into something valid-but-wrong, and a rotate
+# run against a table nobody meant to name is not recoverable.
+_TABLE_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$")
+_COLUMN_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def cmd_key(out: Out) -> int:
+    """Print fresh key material. Touches no config and no database, deliberately - the first
+    key has to be generatable before there is a working install to generate it from."""
+
+    out(generate_key())
+    out("")
+    out('Put it in the environment variable named by config["crypto"]["keys"],')
+    out("not in a config file. Keep the previous key listed until:")
+    out("  python3 src/app.py crypto rotate --table T --column C")
+    out("reports nothing left under it.")
+
+    return 0
+
+
+def _qualified(table: str) -> sql.Composed:
+    """Split an optional schema qualifier so each half is quoted separately.
+
+    Identifier("public.people") quotes the dot into the name, producing "public.people" as
+    a single relation that does not exist.
+    """
+
+    return sql.SQL(".").join(sql.Identifier(part) for part in table.split("."))
+
+
+async def cmd_rotate(
+    conn: psycopg.AsyncConnection,
+    crypto: FieldCrypto,
+    table: str,
+    column: str,
+    id_column: str,
+    batch: int,
+    dry_run: bool,
+    out: Out,
+) -> int:
+    """Re-encrypt a column onto the current key.
+
+    Idempotent: a second run costs a scan and changes nothing. Values already under the
+    current key are skipped, and values that are not encrypted at all are left alone and
+    counted, because a half-backfilled column is a normal state rather than an error.
+    """
+
+    if _TABLE_RE.match(table) is None:
+        out(f"error: {table!r} is not a plain table name")
+        return 2
+
+    if _COLUMN_RE.match(column) is None:
+        out(f"error: --column={column!r} is not a plain column name")
+        return 2
+
+    if _COLUMN_RE.match(id_column) is None:
+        out(f"error: --id={id_column!r} is not a plain column name")
+        return 2
+
+    if batch < 1:
+        out("error: --batch must be at least 1")
+        return 2
+
+    try:
+        current = crypto.current_key_id()
+    except CryptoError as e:
+        out(f"error: {e}")
+        return 1
+
+    out(f"Rotating {table}.{column} onto key {current!r}" + (" (--dry-run)" if dry_run else ""))
+
+    relation = _qualified(table)
+    id_ident = sql.Identifier(id_column)
+    column_ident = sql.Identifier(column)
+
+    # The first page has no cursor. `id > NULL` is unknown rather than true, so it would
+    # match no rows and the whole rotate would report an empty table; the guard makes the
+    # predicate short-circuit instead of writing a second query for the first page.
+    read = sql.SQL(
+        "SELECT {id} AS id, {col} AS value FROM {rel} "
+        "WHERE (%(cursor)s IS NULL OR {id} > %(cursor)s) ORDER BY {id} LIMIT %(batch)s"
+    ).format(id=id_ident, col=column_ident, rel=relation)
+    write = sql.SQL("UPDATE {rel} SET {col} = %s WHERE {id} = %s").format(rel=relation, col=column_ident, id=id_ident)
+
+    cursor: object = None
+    seen = 0
+    rotated = 0
+    plaintext = 0
+
+    while True:
+        try:
+            async with conn.cursor() as cur:
+                # Keyset pagination rather than OFFSET: OFFSET re-reads and discards every
+                # row it skips, so the last page of a large table costs a full scan, and a
+                # row updated mid-run shifts the window under it.
+                await cur.execute(read, {"cursor": cursor, "batch": batch})
+                rows = await cur.fetchall()
+        except psycopg.Error as e:
+            out(f"error: cannot read {table}: {e}")
+            return 1
+
+        if not rows:
+            break
+
+        for row_id, value in rows:
+            seen += 1
+            cursor = row_id
+
+            if value is None or value == "":
+                continue
+
+            found = key_id_of(value)
+            if found is None:
+                plaintext += 1
+                continue
+
+            if found == current:
+                continue
+
+            rotated += 1
+            if dry_run:
+                continue
+
+            try:
+                fresh = crypto.encrypt(str(crypto.decrypt(value)), current)
+            except CryptoError as e:
+                out(f"error: {id_column} {row_id}: {e}")
+                return 1
+
+            try:
+                async with conn.cursor() as cur:
+                    await cur.execute(write, (fresh, row_id))
+            except psycopg.Error as e:
+                out(f"error: {id_column} {row_id}: {e}")
+                return 1
+
+        if len(rows) < batch:
+            break
+
+    out(f"Read {seen} rows.")
+    if plaintext > 0:
+        out(f"{plaintext} were not encrypted and were left alone.")
+    out(f"{rotated} would be re-encrypted." if dry_run else f"{rotated} re-encrypted.")
+
+    return 0

py_app_runner/crypto/envelope.py

@@ -0,0 +1,144 @@
+"""The binary envelope shared with end-to-end encrypted clients.
+
+    magic(3) | version(1) | nonce(12) | ciphertext(n) | tag(16)
+
+This is the format `copasty-server`'s clients already write, where it exists only as
+JavaScript in the share viewer. Having no Python side to it is why the server currently
+validates an uploaded envelope by its length alone and would store arbitrary bytes just as
+happily as a real one.
+
+The magic and version are parameters rather than constants: `CPE` belongs to Copasty, and
+a second application gets its own. Nothing here needs the key - `validate()` is the call a
+server that will never hold one still wants, so that a blob which cannot possibly decrypt
+is refused at upload rather than at read.
+"""
+
+import base64
+import os
+from dataclasses import dataclass
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from py_app_runner.crypto.errors import CryptoError
+
+MAGIC_BYTES = 3
+NONCE_BYTES = 12
+TAG_BYTES = 16
+
+# magic + version + nonce + tag, i.e. an envelope around an empty plaintext. Anything
+# shorter cannot be one whatever it contains.
+MIN_ENVELOPE_BYTES = MAGIC_BYTES + 1 + NONCE_BYTES + TAG_BYTES
+
+
+@dataclass(frozen=True)
+class Envelope:
+    magic: bytes
+    version: int
+    nonce: bytes
+    # Ciphertext with the AEAD tag still appended. Kept joined because that is what both
+    # WebCrypto's decrypt and `cryptography`'s AESGCM.decrypt expect to be handed, so
+    # splitting it here would only mean rejoining it at both call sites.
+    body: bytes
+
+
+def b64url_decode(value: str) -> bytes:
+    """Decode the base64url alphabet, restoring padding first.
+
+    Keys travel to a browser in the URL fragment, which rules out `+` and `/`, and the
+    padding is routinely dropped on the way. `base64.urlsafe_b64decode` rejects a string
+    whose length is not a multiple of four rather than assuming the padding, so it has to
+    be put back before decoding.
+    """
+
+    padded = value + "=" * (-len(value) % 4)
+    try:
+        return base64.urlsafe_b64decode(padded)
+    except (ValueError, TypeError) as e:
+        raise CryptoError(f"Value is not valid base64url: {e}") from e
+
+
+def b64url_encode(raw: bytes) -> str:
+    """Encode to base64url without padding, which is what a URL fragment wants."""
+
+    return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def parse(blob: bytes, magic: bytes = b"CPE", version: int = 1) -> Envelope:
+    """Read an envelope, or raise explaining which part of it is wrong."""
+
+    if len(blob) < MIN_ENVELOPE_BYTES:
+        raise CryptoError(f"Envelope is {len(blob)} bytes, and the header alone needs {MIN_ENVELOPE_BYTES}.")
+
+    if len(magic) != MAGIC_BYTES:
+        raise CryptoError(f"An envelope magic is {MAGIC_BYTES} bytes; {magic!r} is {len(magic)}.")
+
+    found_magic = blob[:MAGIC_BYTES]
+    if found_magic != magic:
+        raise CryptoError(f"Envelope starts with {found_magic!r}, not {magic!r}.")
+
+    found_version = blob[MAGIC_BYTES]
+    if found_version != version:
+        raise CryptoError(
+            f"Envelope is version {found_version}, and this build reads version {version}. "
+            f"It was written by a newer client."
+        )
+
+    return Envelope(
+        magic=found_magic,
+        version=found_version,
+        nonce=blob[MAGIC_BYTES + 1 : MAGIC_BYTES + 1 + NONCE_BYTES],
+        body=blob[MAGIC_BYTES + 1 + NONCE_BYTES :],
+    )
+
+
+def validate(blob: bytes, magic: bytes = b"CPE", version: int = 1) -> None:
+    """Refuse a blob that cannot be an envelope, without needing the key.
+
+    This is the check a server storing opaque ciphertext can still make. It says nothing
+    about whether the payload decrypts - only the holder of the key can know that - but it
+    does stop a client uploading arbitrary bytes into a column the whole system treats as
+    an envelope.
+    """
+
+    parse(blob, magic, version)
+
+
+def pack(nonce: bytes, body: bytes, magic: bytes = b"CPE", version: int = 1) -> bytes:
+    if len(nonce) != NONCE_BYTES:
+        raise CryptoError(f"An envelope nonce is {NONCE_BYTES} bytes; got {len(nonce)}.")
+
+    if len(magic) != MAGIC_BYTES:
+        raise CryptoError(f"An envelope magic is {MAGIC_BYTES} bytes; {magic!r} is {len(magic)}.")
+
+    if not 0 <= version <= 255:
+        raise CryptoError(f"An envelope version is a single byte; got {version}.")
+
+    return magic + bytes([version]) + nonce + body
+
+
+def encrypt(key: bytes, plaintext: bytes, magic: bytes = b"CPE", version: int = 1) -> bytes:
+    """Build an envelope. Only for the case where the server legitimately holds the key.
+
+    An end-to-end encrypted application never calls this: the point there is that the
+    server cannot. It exists for the other case - a server-side blob that happens to use
+    the same wire format, so a browser can be handed the key later and open it.
+    """
+
+    if len(key) != 32:
+        raise CryptoError(f"An envelope key is 32 bytes (AES-256); got {len(key)}.")
+
+    nonce = os.urandom(NONCE_BYTES)
+    body = AESGCM(key).encrypt(nonce, plaintext, None)
+    return pack(nonce, body, magic, version)
+
+
+def decrypt(key: bytes, blob: bytes, magic: bytes = b"CPE", version: int = 1) -> bytes:
+    if len(key) != 32:
+        raise CryptoError(f"An envelope key is 32 bytes (AES-256); got {len(key)}.")
+
+    parsed = parse(blob, magic, version)
+    try:
+        return AESGCM(key).decrypt(parsed.nonce, parsed.body, None)
+    except InvalidTag as e:
+        raise CryptoError("Could not decrypt an envelope: wrong key, or the value has been altered.") from e

py_app_runner/crypto/errors.py

@@ -0,0 +1,8 @@
+class CryptoError(Exception):
+    """Anything wrong with key material, configuration, or a stored value's shape.
+
+    Never caught and turned into a None by this package. A field that cannot be decrypted
+    has to reach somebody: silently returning None puts an empty string in front of a user
+    and leaves the real value sitting unreadable in the database, which is discovered
+    months later when somebody asks why a column is full of blanks.
+    """

py_app_runner/crypto/fields.py

@@ -0,0 +1,300 @@
+"""Field encryption: encrypt a column the application has to read back.
+
+Explicit at every call site. Nothing hooks into the database layer, so a value cannot be
+encrypted twice or written in the clear because a hook did not fire - the two failure modes
+that make transparent column encryption so unpleasant to debug.
+
+Stored values look like:
+
+    pa1:<key_id>:<base64 of nonce(12) || ciphertext || tag(16)>
+
+carrying a version and a key id, which is what lets a retired key keep decrypting old rows,
+lets a column hold plaintext and ciphertext while a backfill runs, and lets `crypto rotate`
+tell what still needs rewriting.
+"""
+
+import base64
+import hashlib
+import hmac
+import os
+import re
+from collections.abc import Callable
+from typing import Any
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from py_app_runner.crypto.errors import CryptoError
+
+VERSION = "pa1"
+KEY_BYTES = 32
+NONCE_BYTES = 12
+TAG_BYTES = 16
+
+# Another field-encryption format in use across the estate, on a different cipher with a
+# 24-byte nonce. Recognised only so that a value in it is refused with an explanation rather
+# than passed through as though it were plaintext, which is what a column mid-backfill would
+# otherwise make it look like.
+_FOREIGN_VERSION = "sp1"
+
+# Lowercase, no dash, no dot, and above all no colon: the id sits next to the ":"
+# separators in the stored value, so a colon in it would make the value unsplittable.
+# Constrained rather than escaped, for the same reason a table name is whitelisted rather
+# than quoted.
+_KEY_ID_RE = re.compile(r"^[a-z0-9_]{1,16}$")
+
+# The blind index key is cached under a reserved id that the pattern above cannot match,
+# so it can never collide with a real key id.
+_INDEX_CACHE_ID = "@index"
+
+Resolver = Callable[[str], str | None]
+
+
+class FieldCrypto:
+    """Holds the configured keys. Build one per process; it caches decoded key material.
+
+    An instance rather than a module of functions, so the decoded-key cache has an obvious
+    lifetime: it is dropped by rebuilding the object. A module-level cache would need an
+    explicit invalidation call that nothing would remember to make after a key change.
+    `AppRegistry` already owns the process-global config this is built from.
+    """
+
+    def __init__(
+        self,
+        key_id: str,
+        keys: dict[str, str],
+        index_key_var: str = "",
+        resolver: Resolver | None = None,
+    ) -> None:
+        self.key_id = key_id
+        self.keys = keys
+        self.index_key_var = index_key_var
+        # Indirection so a test - or a deployment reading from a secrets manager rather than
+        # the environment - can supply key material without setting real environment
+        # variables in the process.
+        self.resolver: Resolver = resolver if resolver is not None else os.environ.get
+        self._cache: dict[str, bytes] = {}
+
+    @classmethod
+    def from_config(cls, config: dict[str, Any], resolver: Resolver | None = None) -> "FieldCrypto":
+        settings = config.get("crypto") or {}
+        raw_keys = settings.get("keys") or {}
+        if not isinstance(raw_keys, dict):
+            raise CryptoError('config["crypto"]["keys"] must be a mapping of key id -> env var name.')
+
+        return cls(
+            key_id=settings.get("key") or "",
+            keys={str(k): str(v) for k, v in raw_keys.items()},
+            index_key_var=settings.get("index_key") or "",
+            resolver=resolver,
+        )
+
+    ####################
+    ### Key material ###
+    ####################
+
+    def current_key_id(self) -> str:
+        if not self.key_id:
+            raise CryptoError(
+                'config["crypto"]["key"] does not name a key to encrypt with. '
+                "Generate one with: python3 src/app.py crypto key"
+            )
+
+        return self._assert_key_id(self.key_id)
+
+    def _assert_key_id(self, key_id: str) -> str:
+        if _KEY_ID_RE.match(key_id) is None:
+            raise CryptoError(f"{key_id!r} is not a usable key id. Use up to 16 of a-z, 0-9 and underscore.")
+
+        return key_id
+
+    def _key(self, key_id: str) -> bytes:
+        self._assert_key_id(key_id)
+
+        cached = self._cache.get(key_id)
+        if cached is not None:
+            return cached
+
+        variable = self.keys.get(key_id)
+        if not variable:
+            raise CryptoError(
+                f'No key {key_id!r} in config["crypto"]["keys"]. A value encrypted under a key id '
+                f"can only be read while that id is still listed, so removing one is permanent."
+            )
+
+        material = self._material(variable, f"key {key_id!r}")
+        self._cache[key_id] = material
+        return material
+
+    def _index_key(self) -> bytes:
+        cached = self._cache.get(_INDEX_CACHE_ID)
+        if cached is not None:
+            return cached
+
+        if not self.index_key_var:
+            raise CryptoError(
+                'config["crypto"]["index_key"] is not set, so blind_index() has no key. '
+                "Generate one with: python3 src/app.py crypto key"
+            )
+
+        material = self._material(self.index_key_var, "the blind index key")
+        self._cache[_INDEX_CACHE_ID] = material
+        return material
+
+    def _material(self, variable: str, label: str) -> bytes:
+        value = self.resolver(variable)
+        if not value:
+            raise CryptoError(
+                f"The environment variable {variable}, holding {label}, is not set. "
+                f"Generate one with: python3 src/app.py crypto key"
+            )
+
+        try:
+            raw = base64.b64decode(value, validate=True)
+        except (ValueError, TypeError) as e:
+            raise CryptoError(
+                f"{variable}, holding {label}, must be {KEY_BYTES} bytes of base64. "
+                f"Generate one with: python3 src/app.py crypto key"
+            ) from e
+
+        if len(raw) != KEY_BYTES:
+            raise CryptoError(
+                f"{variable}, holding {label}, must be {KEY_BYTES} bytes of base64, "
+                f"and decoded to {len(raw)}. "
+                f"Generate one with: python3 src/app.py crypto key"
+            )
+
+        return raw
+
+    ###################
+    ### Encrypt/dec ###
+    ###################
+
+    def encrypt(self, plaintext: str, key_id: str | None = None) -> str:
+        """Encrypt under the current key, or under `key_id` when rotating onto a new one."""
+
+        chosen = key_id if key_id else self.current_key_id()
+        key = self._key(chosen)
+
+        nonce = os.urandom(NONCE_BYTES)
+        # The version and key id are bound as associated data, so the label a value carries
+        # is authenticated rather than merely present. Without this an attacker with write
+        # access to the column could relabel a value's key id; that only ever degrades to a
+        # failed decrypt rather than a forgery, but binding it costs nothing.
+        body = AESGCM(key).encrypt(nonce, plaintext.encode("utf-8"), self._aad(chosen))
+
+        return f"{VERSION}:{chosen}:{base64.b64encode(nonce + body).decode('ascii')}"
+
+    def decrypt(self, value: str | None) -> str | None:
+        """Decrypt a stored value, passing anything that is not one straight through.
+
+        A column being backfilled holds both plaintext and ciphertext at once, so a value
+        that does not carry the format is returned verbatim rather than treated as an error.
+        A value that *does* carry it and still will not open is always an error.
+        """
+
+        if value is None or value == "":
+            return value
+
+        parts = split(value)
+        if parts is None:
+            if value.startswith(f"{_FOREIGN_VERSION}:"):
+                raise CryptoError(
+                    f"This value is in the {_FOREIGN_VERSION!r} field-encryption format, which uses "
+                    f"a different cipher and nonce length. This module reads {VERSION!r} "
+                    f"(AES-256-GCM) and cannot open it."
+                )
+
+            return value
+
+        key_id, payload = parts
+
+        try:
+            raw = base64.b64decode(payload, validate=True)
+        except (ValueError, TypeError) as e:
+            raise CryptoError(f"Encrypted value under key {key_id!r} is not base64") from e
+
+        if len(raw) < NONCE_BYTES + TAG_BYTES:
+            raise CryptoError(
+                f"Encrypted value under key {key_id!r} is truncated: {len(raw)} bytes, and the "
+                f"nonce and tag alone need {NONCE_BYTES + TAG_BYTES}."
+            )
+
+        nonce = raw[:NONCE_BYTES]
+        body = raw[NONCE_BYTES:]
+
+        try:
+            plaintext = AESGCM(self._key(key_id)).decrypt(nonce, body, self._aad(key_id))
+        except InvalidTag as e:
+            # Wrong key or an edited value, and AES-GCM cannot say which. Both mean the same
+            # thing to the caller: do not trust this row.
+            raise CryptoError(
+                f"Could not decrypt a value under key {key_id!r}: wrong key, or the value has been altered"
+            ) from e
+
+        return plaintext.decode("utf-8")
+
+    def _aad(self, key_id: str) -> bytes:
+        return f"{VERSION}:{key_id}".encode("ascii")
+
+    ###################
+    ### Blind index ###
+    ###################
+
+    def blind_index(self, value: str) -> str:
+        """A keyed, deterministic index that restores equality lookups on an encrypted column.
+
+        Store it in a second column and query that. Ranges and LIKE do not come back, and
+        equality across rows becomes visible to anyone holding the table - that is inherent
+        to a deterministic index, and the separate key is what stops a dump-holder simply
+        hashing candidate values to find them.
+
+        Nothing is normalised here. Whether "  Anna " and "anna" should match is a question
+        about the column, not about hashing, so the caller answers it.
+        """
+
+        return hmac.new(self._index_key(), value.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+#########################
+### Format inspection ###
+#########################
+
+
+def split(value: str) -> tuple[str, str] | None:
+    """Pull the key id and payload out of a stored value, or None when it is not one."""
+
+    if not value.startswith(f"{VERSION}:"):
+        return None
+
+    parts = value.split(":", 2)
+    if len(parts) != 3 or parts[1] == "" or parts[2] == "":
+        return None
+
+    if _KEY_ID_RE.match(parts[1]) is None:
+        return None
+
+    return (parts[1], parts[2])
+
+
+def is_encrypted(value: str | None) -> bool:
+    return value is not None and value != "" and split(value) is not None
+
+
+def key_id_of(value: str | None) -> str | None:
+    """Which key a stored value is under, without needing that key to be configured.
+
+    This is what lets `crypto rotate` report on values it cannot decrypt.
+    """
+
+    if value is None or value == "":
+        return None
+
+    parts = split(value)
+    return None if parts is None else parts[0]
+
+
+def generate_key() -> str:
+    """Fresh key material, base64 encoded, for an environment variable."""
+
+    return base64.b64encode(os.urandom(KEY_BYTES)).decode("ascii")

py_app_runner/crypto/passwords.py

@@ -0,0 +1,66 @@
+"""Password hashing.
+
+Thin on purpose. bcrypt already embeds its salt and cost in the `$2b$` string it returns,
+so a schema needs one text column and nothing else - a separate `salt` column stores a
+second copy of something the hash already carries, and has to be kept in step with it for
+no benefit.
+"""
+
+import bcrypt
+
+from py_app_runner.crypto.errors import CryptoError
+
+DEFAULT_ROUNDS = 12
+
+# bcrypt truncates at 72 bytes and, depending on the build, either ignores the rest
+# silently or raises. Neither is a good outcome for a user whose passphrase is long, so the
+# limit is checked here where the message can say what happened.
+MAX_PASSWORD_BYTES = 72
+
+
+class PasswordHasher:
+    def __init__(self, rounds: int = DEFAULT_ROUNDS) -> None:
+        self.rounds = rounds
+
+    def hash(self, password: str) -> str:
+        return bcrypt.hashpw(self._encode(password), bcrypt.gensalt(self.rounds)).decode("ascii")
+
+    def verify(self, password: str, stored: str) -> bool:
+        """False for a wrong password *and* for a malformed hash.
+
+        A stored value that is not a bcrypt hash at all - a truncated column, a migration
+        that put something else there - must not raise out of a login handler, because the
+        answer to "may this person in" is still no.
+        """
+
+        try:
+            return bcrypt.checkpw(self._encode(password), stored.encode("utf-8"))
+        except (ValueError, TypeError):
+            return False
+
+    def needs_rehash(self, stored: str) -> bool:
+        """True when a stored hash was made with fewer rounds than are configured now.
+
+        Call it after a successful verify: that is the one moment the plaintext is in hand
+        and the hash can be upgraded without asking the user for anything.
+        """
+
+        try:
+            cost = int(stored.split("$")[2])
+        except (IndexError, ValueError):
+            # Unparseable means it is not a bcrypt hash this class wrote, so replacing it is
+            # exactly what should happen next time there is a plaintext to do it with.
+            return True
+
+        return cost < self.rounds
+
+    def _encode(self, password: str) -> bytes:
+        raw = password.encode("utf-8")
+        if len(raw) > MAX_PASSWORD_BYTES:
+            raise CryptoError(
+                f"bcrypt hashes at most {MAX_PASSWORD_BYTES} bytes and this password is "
+                f"{len(raw)}. Everything past that is ignored, so accepting it would mean two "
+                f"different passwords unlocking the same account."
+            )
+
+        return raw