altcodepro-polydb-python 2.3.30__tar.gz → 2.5.1__tar.gz

{altcodepro_polydb_python-2.3.30/src/altcodepro_polydb_python.egg-info → altcodepro_polydb_python-2.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: altcodepro-polydb-python
-Version: 2.3.30
+Version: 2.5.1
 Summary: Production-ready multi-cloud database abstraction layer with connection pooling, retry logic, and thread safety
 Author: AltCodePro
 Project-URL: Homepage, https://github.com/altcodepro/polydb-python
@@ -69,6 +69,8 @@ Provides-Extra: generic
 Requires-Dist: pymongo>=4.16.0; extra == "generic"
 Requires-Dist: pika>=1.3.2; extra == "generic"
 Requires-Dist: boto3>=1.42.47; extra == "generic"
+Provides-Extra: security
+Requires-Dist: cryptography>=42.0.0; extra == "security"
 Provides-Extra: all
 Requires-Dist: boto3>=1.42.47; extra == "all"
 Requires-Dist: botocore>=1.42.47; extra == "all"
@@ -83,6 +85,7 @@ Requires-Dist: google-cloud-storage>=3.9.0; extra == "all"
 Requires-Dist: pymongo>=4.16.0; extra == "all"
 Requires-Dist: pika>=1.3.2; extra == "all"
 Requires-Dist: requests>=2.32.5; extra == "all"
+Requires-Dist: cryptography>=42.0.0; extra == "all"
 Provides-Extra: dev
 Requires-Dist: black>=26.1.0; extra == "dev"
 Requires-Dist: flake8>=7.3.0; extra == "dev"

{altcodepro_polydb_python-2.3.30 → altcodepro_polydb_python-2.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "altcodepro-polydb-python"
-version = "2.3.30"
+version = "2.5.1"
 description = "Production-ready multi-cloud database abstraction layer with connection pooling, retry logic, and thread safety"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"
@@ -92,6 +92,8 @@ bolckchain = ["ipfshttpclient>=0.7.0", "web3>=7.14.1"]
 
 generic = ["pymongo>=4.16.0", "pika>=1.3.2", "boto3>=1.42.47"]
 
+security = ["cryptography>=42.0.0"]
+
 all = [
     "boto3>=1.42.47",
     "botocore>=1.42.47",
@@ -106,6 +108,7 @@ all = [
     "pymongo>=4.16.0",
     "pika>=1.3.2",
     "requests>=2.32.5",
+    "cryptography>=42.0.0",
 ]
 
 

{altcodepro_polydb_python-2.3.30 → altcodepro_polydb_python-2.5.1/src/altcodepro_polydb_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: altcodepro-polydb-python
-Version: 2.3.30
+Version: 2.5.1
 Summary: Production-ready multi-cloud database abstraction layer with connection pooling, retry logic, and thread safety
 Author: AltCodePro
 Project-URL: Homepage, https://github.com/altcodepro/polydb-python
@@ -69,6 +69,8 @@ Provides-Extra: generic
 Requires-Dist: pymongo>=4.16.0; extra == "generic"
 Requires-Dist: pika>=1.3.2; extra == "generic"
 Requires-Dist: boto3>=1.42.47; extra == "generic"
+Provides-Extra: security
+Requires-Dist: cryptography>=42.0.0; extra == "security"
 Provides-Extra: all
 Requires-Dist: boto3>=1.42.47; extra == "all"
 Requires-Dist: botocore>=1.42.47; extra == "all"
@@ -83,6 +85,7 @@ Requires-Dist: google-cloud-storage>=3.9.0; extra == "all"
 Requires-Dist: pymongo>=4.16.0; extra == "all"
 Requires-Dist: pika>=1.3.2; extra == "all"
 Requires-Dist: requests>=2.32.5; extra == "all"
+Requires-Dist: cryptography>=42.0.0; extra == "all"
 Provides-Extra: dev
 Requires-Dist: black>=26.1.0; extra == "dev"
 Requires-Dist: flake8>=7.3.0; extra == "dev"

{altcodepro_polydb_python-2.3.30 → altcodepro_polydb_python-2.5.1}/src/altcodepro_polydb_python.egg-info/SOURCES.txt

@@ -75,7 +75,10 @@ src/polydb/observability/logging.py
 src/polydb/services/__init__.py
 src/polydb/services/compliance_service.py
 src/polydb/services/security_service.py
+tests/test_advanced_query_injection.py
 tests/test_atomic_decrement.py
+tests/test_audit_chain_cutover.py
+tests/test_audit_hmac.py
 tests/test_aws.py
 tests/test_azure.py
 tests/test_azure_queue_receipt_handle.py
@@ -83,9 +86,14 @@ tests/test_azure_table_empty_filter.py
 tests/test_azure_table_unpack_entity.py
 tests/test_blockchain.py
 tests/test_cloud_factory.py
+tests/test_field_encryption.py
 tests/test_gcp.py
+tests/test_like_pattern_escaping.py
 tests/test_mongodb.py
 tests/test_multi_engine.py
+tests/test_multitenancy_ddl_injection.py
+tests/test_nosql_operator_injection.py
 tests/test_observability.py
 tests/test_postgresql.py
+tests/test_schema_ddl_injection.py
 tests/test_vercel.py

{altcodepro_polydb_python-2.3.30 → altcodepro_polydb_python-2.5.1}/src/altcodepro_polydb_python.egg-info/requires.txt

@@ -30,6 +30,7 @@ google-cloud-storage>=3.9.0
 pymongo>=4.16.0
 pika>=1.3.2
 requests>=2.32.5
+cryptography>=42.0.0
 
 [aws]
 boto3>=1.42.47
@@ -71,6 +72,9 @@ pymongo>=4.16.0
 [rabbitmq]
 pika>=1.3.2
 
+[security]
+cryptography>=42.0.0
+
 [test]
 pytest>=9.0.2
 pytest-asyncio>=1.2.0

{altcodepro_polydb_python-2.3.30 → altcodepro_polydb_python-2.5.1}/src/polydb/adapters/MongoDBAdapter.py

@@ -14,6 +14,25 @@ from ..types import JsonDict
 from ..models import PartitionConfig
 
 
+def _as_literal(value: Any) -> Any:
+    """Wrap a dict value so Mongo compares it instead of executing it.
+
+    A bare dict on the right-hand side of a field is an *operator expression*
+    to Mongo, so a filter value that came from request input can turn
+    ``{"password": <value>}`` into ``{"password": {"$gt": ""}}`` - a match on
+    every document, i.e. filter/auth bypass and full-collection extraction.
+    ``{"$eq": {...}}`` is exactly the same comparison Mongo performs for a
+    literal subdocument, so legitimate exact-match-on-subdocument queries keep
+    working while ``$``-operators can no longer be smuggled in through a value.
+    """
+    return {"$eq": value} if isinstance(value, dict) else value
+
+
+def _sanitize_query(query: Dict[str, Any]) -> Dict[str, Any]:
+    """Apply _as_literal to every value of a caller-supplied Mongo query."""
+    return {k: _as_literal(v) for k, v in (query or {}).items()}
+
+
 class MongoDBAdapter(NoSQLKVAdapter):
     """MongoDB adapter compatible with PolyDB contract"""
 
@@ -31,6 +50,7 @@ class MongoDBAdapter(NoSQLKVAdapter):
 
         self._client = None
         self._lock = threading.Lock()
+        self._indexed_collections: set = set()
 
         self._initialize_client()
 
@@ -74,7 +94,45 @@ class MongoDBAdapter(NoSQLKVAdapter):
 
         collection_name = meta.get("collection") or meta.get("table") or model.__name__.lower()
 
-        return self._client[self.db_name][collection_name]  # type: ignore
+        collection = self._client[self.db_name][collection_name]  # type: ignore
+
+        self._ensure_pk_rk_index(collection, collection_name)
+
+        return collection
+
+    def _ensure_pk_rk_index(self, collection, collection_name: str) -> None:
+        """
+        Create the compound (_pk, _rk) index once per collection.
+
+        Without it, every _get_raw/_put_raw lookup and query_page's
+        `.sort("_pk")` scan the whole collection -- on Cosmos DB's Mongo
+        API that's a cross-partition fan-out, billed and latent
+        accordingly. Best-effort: a provider that rejects index creation
+        (e.g. restricted tier) shouldn't take the adapter down, so a
+        failure here is logged once and not retried on every call.
+        Note: this is a logical uniqueness/query index only -- it does
+        NOT retroactively set Cosmos's physical shard key, which can only
+        be chosen at container-creation time.
+        """
+        if collection_name in self._indexed_collections:
+            return
+
+        with self._lock:
+            if collection_name in self._indexed_collections:
+                return
+
+            try:
+                collection.create_index(
+                    [("_pk", 1), ("_rk", 1)], unique=True, name="pk_rk_unique"
+                )
+            except Exception:
+                self.logger.warning(
+                    "Could not ensure (_pk, _rk) index on %s",
+                    collection_name,
+                    exc_info=True,
+                )
+            finally:
+                self._indexed_collections.add(collection_name)
 
     # -----------------------------------------------------
     # PUT
@@ -87,7 +145,11 @@ class MongoDBAdapter(NoSQLKVAdapter):
             payload = dict(data or {})
             payload["_pk"] = pk
             payload["_rk"] = rk
-            payload["id"] = pk
+            # _rk is the record's natural identifier (the base class
+            # already falls back to `id` when a model has no explicit
+            # sort_key); _pk is just the tenant/partition grouping, so it
+            # must never overwrite a caller-supplied `id`.
+            payload.setdefault("id", rk)
 
             collection.update_one(
                 {"_pk": pk, "_rk": rk},
@@ -120,7 +182,7 @@ class MongoDBAdapter(NoSQLKVAdapter):
                 return None
 
             doc.pop("_id", None)
-            doc.setdefault("id", pk)
+            doc.setdefault("id", rk)
 
             return doc
 
@@ -140,7 +202,9 @@ class MongoDBAdapter(NoSQLKVAdapter):
         try:
             collection = self._get_collection(model)
 
-            query = query or {}
+            # Sanitize before adding our own operator clause below, so the
+            # pagination cursor isn't stripped along with injected operators.
+            query = _sanitize_query(query)
 
             if continuation_token:
                 query["_pk"] = {"$gt": continuation_token}
@@ -151,7 +215,7 @@ class MongoDBAdapter(NoSQLKVAdapter):
 
             for doc in cursor:
                 doc.pop("_id", None)
-                doc.setdefault("id", doc.get("_pk"))
+                doc.setdefault("id", doc.get("_rk"))
                 rows.append(doc)
 
             if not rows:
@@ -179,7 +243,7 @@ class MongoDBAdapter(NoSQLKVAdapter):
             for k, v in (filters or {}).items():
 
                 if k == "id":
-                    query["_pk"] = v
+                    query["_rk"] = _as_literal(v)
                     continue
 
                 if k.endswith("__gt"):
@@ -195,7 +259,10 @@ class MongoDBAdapter(NoSQLKVAdapter):
                     query[k[:-5]] = {"$lte": v}
 
                 elif k.endswith("__in"):
-                    query[k[:-4]] = {"$in": v}
+                    # $in operands are matched literally by Mongo, but the list
+                    # itself has to be a list - a dict here would be read as an
+                    # operator document.
+                    query[k[:-4]] = {"$in": list(v) if isinstance(v, (list, tuple, set)) else [v]}
 
                 elif k.endswith("__contains"):
                     safe_pattern = re.escape(str(v))
@@ -205,7 +272,7 @@ class MongoDBAdapter(NoSQLKVAdapter):
                     }
 
                 else:
-                    query[k] = v
+                    query[k] = _as_literal(v)
 
             cursor = collection.find(query)
 
@@ -216,7 +283,7 @@ class MongoDBAdapter(NoSQLKVAdapter):
 
             for doc in cursor:
                 doc.pop("_id", None)
-                doc.setdefault("id", doc.get("_pk"))
+                doc.setdefault("id", doc.get("_rk"))
                 results.append(doc)
 
             return results
@@ -238,7 +305,7 @@ class MongoDBAdapter(NoSQLKVAdapter):
             if result.deleted_count == 0:
                 raise DatabaseError(f"Item {pk}/{rk} does not exist")
 
-            return {"id": pk}
+            return {"id": rk}
 
         except DatabaseError:
             raise

{altcodepro_polydb_python-2.3.30 → altcodepro_polydb_python-2.5.1}/src/polydb/adapters/PostgreSQLAdapter.py

@@ -76,7 +76,7 @@ class PostgreSQLAdapter:
     def _initialize_pool(self):
         try:
             import psycopg2.pool
-            from urllib.parse import urlparse, parse_qs, urlencode, urlunparse
+            from urllib.parse import urlparse, parse_qs, quote, urlencode, urlunparse
 
             dsn = self.connection_string
             if "postgresql://" in dsn:
@@ -108,7 +108,12 @@ class PostgreSQLAdapter:
                     [f"-c statement_timeout={os.getenv('POSTGRES_STATEMENT_TIMEOUT_MS', '20000')}"],
                 )
 
-                new_query = urlencode(query, doseq=True)
+                # quote_via=quote, not the default quote_plus: libpq's URI
+                # parser percent-decodes query values but treats "+" as a
+                # literal plus, so form-encoding the space in
+                # "-c statement_timeout=..." makes the server see the option
+                # name as "+statement_timeout" and reject the connection.
+                new_query = urlencode(query, doseq=True, quote_via=quote)
                 parsed = parsed._replace(query=new_query)
                 dsn = urlunparse(parsed)
 

{altcodepro_polydb_python-2.3.30 → altcodepro_polydb_python-2.5.1}/src/polydb/advanced_query.py

@@ -5,6 +5,45 @@ Advanced query capabilities: JOIN, subqueries, aggregates
 from typing import List, Optional, Any, Dict
 from dataclasses import dataclass, field
 from enum import Enum
+import re
+
+from .errors import ValidationError
+from .utils import validate_table_name, validate_column_name
+
+# table.column / alias.column - each half validated with the same allowlists
+# used elsewhere for identifiers, joined by a single literal dot.
+_QUALIFIED_COLUMN_RE = re.compile(r"^[a-zA-Z0-9_-]+\.[a-zA-Z0-9_]+$")
+
+
+def _validate_qualified_column(value: str) -> str:
+    """Validate a column reference that may be table/alias-qualified (a.b) or bare (b)."""
+    if not isinstance(value, str) or not value:
+        raise ValidationError(f"Invalid column reference: {value!r}")
+    if _QUALIFIED_COLUMN_RE.match(value):
+        return value
+    return validate_column_name(value)
+
+
+# Safe HAVING grammar: one or more `FUNC(col) OP operand` comparisons joined by
+# AND/OR. No string literals, no semicolons/comments, no subqueries - this is
+# an allowlist, not a sanitizer, so anything outside this shape is rejected.
+_IDENT = r"[A-Za-z_][A-Za-z0-9_]*"
+_QUALIFIED = rf"{_IDENT}(?:\.{_IDENT})?"
+_FUNC_CALL = rf"{_IDENT}\(\s*(?:\*|{_QUALIFIED})\s*\)"
+_OPERAND = rf"(?:{_FUNC_CALL}|{_QUALIFIED}|-?\d+(?:\.\d+)?)"
+_COMPARISON_OP = r"(?:!=|<>|>=|<=|=|<|>)"
+_CONDITION = rf"{_OPERAND}\s*{_COMPARISON_OP}\s*{_OPERAND}"
+_HAVING_RE = re.compile(rf"^{_CONDITION}(?:\s+(?:AND|OR)\s+{_CONDITION})*$", re.IGNORECASE)
+
+
+def _validate_having_condition(condition: str) -> str:
+    if not isinstance(condition, str) or not _HAVING_RE.match(condition.strip()):
+        raise ValidationError(
+            f"Invalid HAVING condition: {condition!r}. Only simple aggregate "
+            'comparisons such as "COUNT(id) > 5" (optionally chained with AND/OR) '
+            "are allowed - no string literals, subqueries, or statement separators."
+        )
+    return condition
 
 
 class JoinType(Enum):
@@ -49,6 +88,13 @@ class AdvancedQueryBuilder:
     having_conditions: List[str] = field(default_factory=list)
     subqueries: Dict[str, "AdvancedQueryBuilder"] = field(default_factory=dict)
 
+    def __post_init__(self) -> None:
+        validate_table_name(self.table)
+        for gf in self.group_by_fields:
+            _validate_qualified_column(gf)
+        for cond in self.having_conditions:
+            _validate_having_condition(cond)
+
     def join(
         self,
         table: str,
@@ -58,6 +104,11 @@ class AdvancedQueryBuilder:
         alias: Optional[str] = None,
     ) -> "AdvancedQueryBuilder":
         """Add JOIN clause"""
+        validate_table_name(table)
+        _validate_qualified_column(on_left)
+        _validate_qualified_column(on_right)
+        if alias is not None:
+            validate_column_name(alias)
         self.joins.append(
             Join(table=table, join_type=join_type, on_left=on_left, on_right=on_right, alias=alias)
         )
@@ -67,16 +118,27 @@ class AdvancedQueryBuilder:
         self, function: AggregateFunction, field: str, alias: str
     ) -> "AdvancedQueryBuilder":
         """Add aggregate function"""
+        if field != "*":
+            _validate_qualified_column(field)
+        validate_column_name(alias)
         self.aggregates.append(Aggregate(function=function, field=field, alias=alias))
         return self
 
     def group_by(self, *fields: str) -> "AdvancedQueryBuilder":
         """Add GROUP BY"""
+        for f in fields:
+            _validate_qualified_column(f)
         self.group_by_fields.extend(fields)
         return self
 
     def having(self, condition: str) -> "AdvancedQueryBuilder":
-        """Add HAVING clause"""
+        """Add HAVING clause.
+
+        `condition` must match the safe aggregate-comparison grammar enforced
+        by `_validate_having_condition` (e.g. "COUNT(id) > 5") - free-form SQL
+        text is rejected to prevent HAVING-clause injection.
+        """
+        _validate_having_condition(condition)
         self.having_conditions.append(condition)
         return self
 

{altcodepro_polydb_python-2.3.30 → altcodepro_polydb_python-2.5.1}/src/polydb/audit/AuditStorage.py

@@ -1,7 +1,9 @@
 # src/polydb/audit/AuditStorage.py
 from __future__ import annotations
 
+import hmac
 import threading
+from dataclasses import dataclass
 from typing import Optional, Dict, Any
 
 from .models import AuditRecord
@@ -97,7 +99,20 @@ class AuditStorage:
         and re-chains instead of forking. (threading.Lock alone was only
         process-local — the old "distributed-safe" claim was false.)"""
         from dataclasses import asdict
-        from .models import compute_audit_hash
+        from .models import (
+            AuditKeyMissingError,
+            AUDIT_HMAC_KEY_ENV,
+            audit_hmac_key,
+            compute_audit_hash,
+            require_hmac,
+        )
+
+        if require_hmac() and audit_hmac_key() is None:
+            raise AuditKeyMissingError(
+                f"{AUDIT_HMAC_KEY_ENV} is unset. An unkeyed audit hash can be "
+                "recomputed by anyone who can write the log, so this "
+                "deployment has asked to refuse writing one."
+            )
 
         last_err: Optional[Exception] = None
         for _ in range(8):
@@ -139,11 +154,38 @@ class AuditStorage:
         raise last_err or RuntimeError("audit persist failed after retries")
 
     def verify_chain(self, tenant_id: Optional[str] = None) -> bool:
-        """Verify BOTH chain linkage AND per-record content integrity.
-        The old version only checked previous_hash linkage, so editing
-        before/after/action while leaving `hash` intact passed silently."""
+        """Verify BOTH chain linkage AND per-record content integrity."""
+        return self.verify_chain_detailed(tenant_id).ok
+
+    def verify_chain_detailed(
+        self, tenant_id: Optional[str] = None
+    ) -> "ChainVerification":
+        """Verify the chain, reporting *why* rather than only whether.
+
+        Two things are checked per record: that it links to its predecessor,
+        and that its own digest still matches its content. The second is what
+        catches an editor who changed ``before``/``after``/``action`` and left
+        ``hash`` alone.
+
+        Records written before ``POLYDB_AUDIT_HMAC_KEY`` was configured carry
+        an unkeyed SHA-256 and cannot be re-verified with the key. They are
+        accepted, but only *before* the first keyed record in the chain -- and
+        that restriction is what keeps it from being a loophole rather than a
+        migration path:
+
+        * An attacker cannot append unkeyed records after the cutover, because
+          once a keyed record has been seen every later record must be keyed.
+        * An attacker cannot rewrite the legacy prefix either. Rewriting record
+          N means recomputing ``hash(N)``, which is ``previous_hash`` inside
+          record N+1's payload -- and if N+1 is keyed, its digest cannot be
+          recomputed without the key.
+
+        So configuring a key seals everything written up to that moment as well
+        as everything after it. ``legacy_records`` reports how much of the
+        chain is still resting on that seal.
+        """
         from ..query import QueryBuilder, Operator
-        from .models import compute_audit_hash
+        from .models import audit_hmac_key, compute_audit_hash
 
         builder = QueryBuilder()
         if tenant_id is not None:
@@ -152,13 +194,69 @@ class AuditStorage:
 
         records = self.sql.query_linq("polydb_audit_log", builder)
         if not records:
-            return True
+            return ChainVerification(ok=True)
 
+        key = audit_hmac_key()
         prev = ""
-        for r in records:
+        legacy = 0
+        seen_keyed = False
+
+        for index, r in enumerate(records):
+            audit_id = r.get("audit_id")
+
             if (r.get("previous_hash") or "") != prev:
-                return False
-            if r.get("hash") != compute_audit_hash(r):  # content tamper check
-                return False
-            prev = r.get("hash")
-        return True
+                return ChainVerification(
+                    ok=False,
+                    broken_at=index,
+                    audit_id=audit_id,
+                    reason="link",
+                    legacy_records=legacy,
+                )
+
+            stored = r.get("hash") or ""
+
+            if key is not None and hmac.compare_digest(
+                stored, compute_audit_hash(r, key=key)
+            ):
+                seen_keyed = True
+            elif not seen_keyed and hmac.compare_digest(
+                stored, compute_audit_hash(r, key=None)
+            ):
+                # Predates the key. Sealed by the first keyed record that
+                # follows it, so it is only trusted while none has appeared.
+                legacy += 1
+            else:
+                # Distinguish the two ways this arrives. If the *unkeyed*
+                # digest matches the record as stored, the content is intact
+                # and the record simply was not keyed - which after the
+                # cutover is what stripping the key looks like. Otherwise the
+                # record itself was edited.
+                downgraded = seen_keyed and hmac.compare_digest(
+                    stored, compute_audit_hash(r, key=None)
+                )
+                return ChainVerification(
+                    ok=False,
+                    broken_at=index,
+                    audit_id=audit_id,
+                    reason="unkeyed_after_cutover" if downgraded else "content",
+                    legacy_records=legacy,
+                )
+
+            prev = stored
+
+        return ChainVerification(ok=True, legacy_records=legacy)
+
+
+@dataclass(frozen=True)
+class ChainVerification:
+    """The outcome of :meth:`AuditStorage.verify_chain_detailed`."""
+
+    ok: bool
+    broken_at: Optional[int] = None
+    audit_id: Optional[str] = None
+    #: "link" (previous_hash mismatch), "content" (record edited), or
+    #: "unkeyed_after_cutover" (an unkeyed record appended after keying began,
+    #: which is what stripping the key would look like).
+    reason: Optional[str] = None
+    #: How many leading records still carry a pre-key unkeyed digest.
+    legacy_records: int = 0

{altcodepro_polydb_python-2.3.30 → altcodepro_polydb_python-2.5.1}/src/polydb/audit/models.py

@@ -1,13 +1,71 @@
 # src/polydb/audit/models.py
+"""The audit record and its integrity hash.
+
+The chain used a plain SHA-256 over the record's canonical payload. That
+detects accidental corruption and it detects an editor who forgets to
+recompute the hash - but it does not detect the adversary an audit log exists
+for. Anyone who can write the table can also recompute SHA-256, so they can
+rewrite a record, re-hash it, and re-hash every record after it: the chain
+still verifies, and the tampering is invisible. The digest was unkeyed, so
+"can write the log" implied "can forge the log".
+
+``POLYDB_AUDIT_HMAC_KEY`` turns the digest into HMAC-SHA256. The output is
+still 64 hex characters, so it fits the existing ``VARCHAR(64)`` columns and
+needs no migration - only the way the value is derived changes.
+
+Records written before a key was configured stay verifiable. See
+``AuditStorage.verify_chain`` for the cutover rule that makes that safe rather
+than a loophole.
+"""
 
 from dataclasses import dataclass, asdict
 from typing import Any, Dict, List, Optional
-import uuid
 import hashlib
+import hmac
 import json
+import logging
+import os
+import uuid
 from datetime import datetime, timezone
 from ..json_safe import json_safe
 
+logger = logging.getLogger("polydb.audit")
+
+#: Env var holding the audit HMAC key. Absent means legacy unkeyed hashing.
+AUDIT_HMAC_KEY_ENV = "POLYDB_AUDIT_HMAC_KEY"
+
+#: Set to 1/true/yes to refuse to write audit records without a key, for
+#: deployments that would rather fail than keep a forgeable log.
+AUDIT_REQUIRE_HMAC_ENV = "POLYDB_AUDIT_REQUIRE_HMAC"
+
+_warned_no_key = False
+
+#: Distinguishes "caller did not specify a key" from "caller specified None",
+#: which verification needs in order to check the legacy variant deliberately.
+_UNSET = object()
+
+
+class AuditKeyMissingError(RuntimeError):
+    """No audit HMAC key, and the deployment asked to require one."""
+
+
+def audit_hmac_key() -> Optional[bytes]:
+    """The configured audit key, or ``None``.
+
+    Read per call rather than cached so a key rotated into the environment
+    takes effect without a restart, and so tests can set it per case.
+    """
+    raw = os.getenv(AUDIT_HMAC_KEY_ENV, "").strip()
+    return raw.encode("utf-8") if raw else None
+
+
+def require_hmac() -> bool:
+    return os.getenv(AUDIT_REQUIRE_HMAC_ENV, "").strip().lower() in (
+        "1",
+        "true",
+        "yes",
+    )
+
 
 def _iso(ts: Any) -> str:
     return ts.isoformat() if hasattr(ts, "isoformat") else str(ts)
@@ -43,8 +101,42 @@ def canonical_audit_payload(src: Dict[str, Any]) -> str:
     return json.dumps(payload, sort_keys=True, default=json_safe)
 
 
-def compute_audit_hash(src: Dict[str, Any]) -> str:
-    return hashlib.sha256(canonical_audit_payload(src).encode()).hexdigest()
+def compute_audit_hash(
+    src: Dict[str, Any], *, key: Optional[bytes] = _UNSET  # type: ignore[assignment]
+) -> str:
+    """The record's integrity digest, keyed when a key is available.
+
+    ``key`` defaults to whatever the environment provides; pass it explicitly
+    (including ``None``) to compute a specific variant, which is what
+    verification does when it has to check a record written under the other
+    scheme.
+    """
+    if key is _UNSET:
+        key = audit_hmac_key()
+        if key is None:
+            _warn_unkeyed_once()
+
+    payload = canonical_audit_payload(src).encode()
+    if key is None:
+        return hashlib.sha256(payload).hexdigest()
+    return hmac.new(key, payload, hashlib.sha256).hexdigest()
+
+
+def _warn_unkeyed_once() -> None:
+    global _warned_no_key
+    if _warned_no_key:
+        return
+    _warned_no_key = True
+    logger.warning(
+        "Audit records are being hashed without a key (%s is unset). The "
+        "chain still detects accidental corruption, but anyone who can write "
+        "polydb_audit_log can recompute it, so it does not detect deliberate "
+        "tampering. Set %s to seal the log; set %s=1 to refuse to write "
+        "without one.",
+        AUDIT_HMAC_KEY_ENV,
+        AUDIT_HMAC_KEY_ENV,
+        AUDIT_REQUIRE_HMAC_ENV,
+    )
 
 
 @dataclass