def create_encrypted_connection(
    path: str | Path,
    key: str | bytes,
    *,
    check_same_thread: bool = False,
    timeout: float = 30.0,
) -> sqlite3.Connection:
    """
    Create an encrypted SQLite connection using SQLCipher.

    SQLCipher provides transparent AES-256 encryption at the page level,
    with hardware acceleration on CPUs supporting AES-NI.

    Args:
        path: Database file path (cannot be ":memory:" for encryption)
        key: Encryption passphrase or 32-byte raw key
        check_same_thread: SQLite thread-safety setting
        timeout: Connection timeout in seconds

    Returns:
        sqlite3.Connection with encryption enabled

    Raises:
        EncryptionUnavailableError: If sqlcipher3 is not installed
        EncryptionError: If encryption setup fails
        ValueError: If trying to encrypt an in-memory database
    """
    path_str = str(path)

    if path_str == ":memory:":
        raise ValueError(
            "In-memory databases cannot be encrypted. "
            "Use a file path for encrypted databases."
        )

    try:
        from sqlcipher3 import dbapi2 as sqlcipher  # type: ignore
    except ImportError:
        raise EncryptionUnavailableError()

    # Resolve the per-DB salt. For a brand-new database, generate and write
    # a random sidecar; for an existing one, prefer the sidecar but fall
    # back to the legacy fixed salt so pre-2.6.0 databases keep opening.
    db_path_obj = Path(path_str)
    is_new_db = not db_path_obj.exists() or db_path_obj.stat().st_size == 0
    salt = _resolve_salt(db_path_obj, create_if_missing=is_new_db)

    try:
        conn = sqlcipher.connect(  # type: ignore[attr-defined]
            path_str,
            check_same_thread=check_same_thread,
            timeout=timeout,
        )

        # Set the encryption key using PRAGMA. PRAGMA arguments cannot be
        # parameterized via ``?`` placeholders, so we must interpolate. To
        # avoid ever interpolating user-supplied passphrase characters into a
        # quoted SQL string (where escape rules are subtle and SQLCipher
        # parsing has surprising edge cases), normalize *every* key path to
        # 32 bytes via ``_normalize_key`` and feed it as ``x'hex'`` raw-key
        # form. The hex output is restricted to ``[0-9a-f]`` so no quoting
        # or escaping is needed.
        normalized_key = _normalize_key(key, salt=salt)
        conn.execute(f"PRAGMA key = \"x'{normalized_key.hex()}'\"")

        # Verify encryption is working by querying cipher_version
        try:
            result = conn.execute("PRAGMA cipher_version").fetchone()
            if result is None:
                raise EncryptionError(
                    "SQLCipher encryption not active. Database may be corrupted "
                    "or key is incorrect."
                )
            _logger.debug("SQLCipher version: %s", result[0])

            # Validate key by actually reading from the database
            # cipher_version only confirms SQLCipher is loaded, not that the key is correct
            # Reading sqlite_master forces decryption and will fail with wrong key
            conn.execute("SELECT count(*) FROM sqlite_master").fetchone()
        except EncryptionError:
            raise
        except Exception as e:
            conn.close()
            raise EncryptionError(
                f"Failed to verify encryption (wrong key?): {e}"
            ) from e

        # Set performance optimizations (same as non-encrypted)
        conn.execute("PRAGMA journal_mode=WAL")
        conn.execute("PRAGMA synchronous=NORMAL")

        return conn  # type: ignore[return-value]

    except EncryptionError:
        raise
    except Exception as e:
        raise EncryptionError(f"Failed to create encrypted connection: {e}") from e

def is_database_encrypted(path: str | Path) -> bool:
    """
    Check if a database file is encrypted.

    Attempts to open with standard sqlite3. If it fails with "not a database",
    the file is likely encrypted.

    Args:
        path: Path to database file

    Returns:
        True if database appears to be encrypted
    """
    path = Path(path)
    if not path.exists():
        return False
    # A zero-byte file would cause sqlite3 to create a fresh DB and return
    # False, masking a missing/corrupt database as unencrypted. Treat empty
    # files as not encrypted but also not a real DB; callers that need to
    # distinguish should check existence and size themselves.
    if _is_zero_byte(path):
        return False

    try:
        conn = sqlite3.connect(str(path))
        # Try to read the schema - this will fail if encrypted
        conn.execute("SELECT name FROM sqlite_master LIMIT 1").fetchone()
        conn.close()
        return False
    except sqlite3.DatabaseError as e:
        if "not a database" in str(e).lower() or "encrypted" in str(e).lower():
            return True
        raise

def encrypt_file(
    input_path: Path,
    output_path: Path,
    key: bytes,
) -> None:
    """
    Encrypt a file using AES-256-GCM.

    File format:
    - 12 bytes: nonce
    - N bytes: ciphertext
    - 16 bytes: GCM auth tag (appended by cryptography)

    Args:
        input_path: Path to plaintext file
        output_path: Path for encrypted output
        key: 32-byte encryption key

    Raises:
        EncryptionUnavailableError: If cryptography is not installed
        EncryptionError: If encryption fails
    """
    try:
        from cryptography.hazmat.primitives.ciphers.aead import AESGCM
    except ImportError:
        raise EncryptionUnavailableError()

    try:
        # Read plaintext
        plaintext = input_path.read_bytes()

        # Generate random nonce (MUST be unique per encryption)
        nonce = secrets.token_bytes(AES_NONCE_SIZE)

        # Encrypt with AES-GCM. Bind the v1 header (magic + version) into
        # the GCM AAD so any tampering with the header bytes — including a
        # downgrade attempt that strips the version byte — fails
        # authentication on decrypt.
        header = _ENC_MAGIC + bytes([_ENC_VERSION])
        aesgcm = AESGCM(key)
        ciphertext = aesgcm.encrypt(nonce, plaintext, associated_data=header)

        # Atomically write: header + nonce + ciphertext to a sibling temp
        # file, fsync, restrict permissions, then os.replace() onto the
        # target path. A crash mid-write leaves only the temp file; the
        # target is never torn.
        _atomic_write_bytes(
            output_path, header + nonce + ciphertext, mode=0o600
        )

        _logger.debug(
            "Encrypted %d bytes -> %d bytes",
            len(plaintext),
            len(nonce) + len(ciphertext),
        )

    except Exception as e:
        raise EncryptionError(f"Failed to encrypt file: {e}") from e

def decrypt_file(
    input_path: Path,
    output_path: Path,
    key: bytes,
) -> None:
    """
    Decrypt a file encrypted with encrypt_file().

    Args:
        input_path: Path to encrypted file
        output_path: Path for decrypted output
        key: 32-byte encryption key

    Raises:
        EncryptionUnavailableError: If cryptography is not installed
        EncryptionError: If decryption fails (wrong key, corrupted data)
    """
    try:
        from cryptography.hazmat.primitives.ciphers.aead import AESGCM
    except ImportError:
        raise EncryptionUnavailableError()

    try:
        # Read encrypted data
        data = input_path.read_bytes()

        # Detect format. v1 starts with magic 'SV' + version byte; anything
        # else is treated as v0 (pre-2.6.0) for backwards compatibility.
        # The v1 header is bound into the GCM AAD on encrypt, so any
        # tampering with the magic/version bytes — including a downgrade
        # attempt that strips them — fails authentication here.
        associated_data: bytes | None = None
        if (
            len(data) >= _ENC_HEADER_LEN
            and data[: len(_ENC_MAGIC)] == _ENC_MAGIC
            and data[len(_ENC_MAGIC)] == _ENC_VERSION
        ):
            associated_data = bytes(data[:_ENC_HEADER_LEN])
            data = data[_ENC_HEADER_LEN:]

        if len(data) < AES_NONCE_SIZE + AES_TAG_SIZE:
            raise EncryptionError("Encrypted file too small to be valid")

        # Extract nonce and ciphertext
        nonce = data[:AES_NONCE_SIZE]
        ciphertext = data[AES_NONCE_SIZE:]

        # Decrypt with AES-GCM. associated_data is bound to the v1 header
        # (or None for legacy v0 files where no header was present).
        aesgcm = AESGCM(key)
        plaintext = aesgcm.decrypt(nonce, ciphertext, associated_data=associated_data)

        # Write decrypted data atomically. Plaintext is sensitive — restrict
        # permissions to owner only.
        _atomic_write_bytes(output_path, plaintext, mode=0o600)

        _logger.debug(
            "Decrypted %d bytes -> %d bytes",
            len(data),
            len(plaintext),
        )

    except EncryptionError:
        raise
    except Exception as e:
        # InvalidTag is raised by cryptography when decryption fails (wrong key/corrupted)
        exc_type = type(e).__name__
        exc_msg = str(e).lower()
        if "tag" in exc_type.lower() or "tag" in exc_msg or "authentication" in exc_msg:
            raise EncryptionError(
                "Decryption failed: wrong key or corrupted data"
            ) from e
        raise EncryptionError(f"Failed to decrypt file: {e}") from e