altcodepro-polydb-python 2.3.31__py3-none-any.whl → 2.5.2__py3-none-any.whl

{altcodepro_polydb_python-2.3.31.dist-info → altcodepro_polydb_python-2.5.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: altcodepro-polydb-python
-Version: 2.3.31
+Version: 2.5.2
 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.31.dist-info → altcodepro_polydb_python-2.5.2.dist-info}/RECORD

@@ -1,23 +1,23 @@
-altcodepro_polydb_python-2.3.31.dist-info/licenses/LICENSE,sha256=9X8GLocsBwy-5aR5JGOt2SAMDDPs9Qv-YnqmHBHOXrw,1067
+altcodepro_polydb_python-2.5.2.dist-info/licenses/LICENSE,sha256=9X8GLocsBwy-5aR5JGOt2SAMDDPs9Qv-YnqmHBHOXrw,1067
 polydb/PolyDB.py,sha256=MG7-nV59zDvrUQwXNEgV4eetHCeW9TYY9DQqtxu_r7k,23543
 polydb/__init__.py,sha256=d9KSz888A336904TPEjWPYBtyJLPB0lTdcaOnYp8byY,1535
-polydb/advanced_query.py,sha256=cxMB-EB-qT3bWXJlhmjnMCUtrzogORWyoEfS50Dy7go,4280
+polydb/advanced_query.py,sha256=JZUQr4wyC9ydrcO9VbZiH2ueiQiC4dxOX9hzG_JaFhs,6931
 polydb/batch.py,sha256=_DjWZa1ZXYSk6MLKqFe0eT7SYVRZtYNqZb9bI8Y2sao,4566
 polydb/cache.py,sha256=JBXF1XEK-fY80ar8SDE893Z1Z116YtXAEG0PaJ0Nkcw,7658
 polydb/cloudDatabaseFactory.py,sha256=Gp6L__YtgrkGahD8B7ItzXMHCoj2ZUGDjXLS9w0TujY,17780
 polydb/databaseFactory.py,sha256=AdEMRtWcwf0elJ9JhrWS5krre-3RVFfIgt0mA93eJJQ,44068
 polydb/decorators.py,sha256=L_WP2uXP_k8Ac49SUm-mthbM4jWI-XYfHXEyKzumOww,43062
-polydb/errors.py,sha256=jF_55fbfg6b6mBc116dzU_uBG9qiIKbr5jvmDuJx-Jw,1573
+polydb/errors.py,sha256=ZM3XEefhDMo82v3MMRQ7CRLdKI4N_lYLZN6O0ajBM7M,1712
 polydb/json_safe.py,sha256=R5PrqAGirqjYKPyy-8KH-lSXjLH0FPr2TSGozy4eheU,149
 polydb/models.py,sha256=pkGpYnEEJmXdoWVpWS2K3CnuO9JZ_91DKp1bpVNQCns,10259
 polydb/monitoring.py,sha256=UMm3ybyRJjAQi-prXXMLl9zuHhnhMnYBzMD3XWK66y8,9571
-polydb/multitenancy.py,sha256=9kyY98RpKg8xDy9ejB_MyV_YzF7eZd4uxashw5S8vlg,6408
+polydb/multitenancy.py,sha256=BfnSJRRyRl4ObM4noXDJhsGJHLESXzvYRsdKwic7TQc,8135
 polydb/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-polydb/query.py,sha256=3oWgRXIYLItmd_R-7u78hCdUgUaoiFmjVg38vi2-rVA,6600
+polydb/query.py,sha256=72QbnQaljNGvIWktSD29BII0476MMjrJ-7dQmOcWuZc,8509
 polydb/registry.py,sha256=RD_elvFXcmhTdCyZDm2f3ej0elxqhArnSJ2aO9k5VCU,2352
 polydb/retry.py,sha256=QduWwDyiU-dt1fHFQmm6ltbnaJY2460cDfQ7ZE8wjXs,4466
-polydb/schema.py,sha256=VrOayX6V6AD2Qh3-lm4ZVPTpI24e4V52IYheZf2rNQ4,5812
-polydb/security.py,sha256=9ju-hc6Y1sxobCoV_mZ3ZWroUD73LodyTLVMhY_HeKU,16360
+polydb/schema.py,sha256=hI7uJM4WvH31A-h0kGZhCD5mCYcnrNvEega--_kvafE,6889
+polydb/security.py,sha256=KqV5cD19hLyIvykW2DkKCXuj1hBDLt3xQ1tFtz_sCQE,20202
 polydb/types.py,sha256=XB_85Un8_aWt4dSfpjIGotHbK3KBY2WurQGXr9EOxWY,2992
 polydb/utils.py,sha256=tS_KI1vt-VZ6JftbFxbnVxC0xpie1-zYikTGf1nSoFw,3183
 polydb/validation.py,sha256=a1o1d02k3c6PWQwkBbw_0nEmIgrdB5RR8OcpNQMn4cA,4810
@@ -35,7 +35,7 @@ polydb/adapters/FirestoreAdapter.py,sha256=e3DEODOZ-UAWULLtGTIED-Ym1JrxOKaOLPQVK
 polydb/adapters/GCPFilestoreAdapter.py,sha256=yjFQQwsWYWc8mo8XwMViVTWb5_D--xAyTMvE-4AOpNM,3006
 polydb/adapters/GCPPubSubAdapter.py,sha256=7XNots2VA0ReEDku-rjg-OTYmftIpx5UgnXYDdXNkOo,8692
 polydb/adapters/GCPStorageAdapter.py,sha256=9yS1Jhcn5_rCRdZ5uOqcRW6Ba-UNb6VOYpwENP-C6Qk,7133
-polydb/adapters/MongoDBAdapter.py,sha256=Ak8q_qeAaUTe0Yc2oEefmAbzoODjTWVZQOirW-seBQU,7574
+polydb/adapters/MongoDBAdapter.py,sha256=qB7RwQb3tvSLLPBiKV_BoAHCvl8Me3C02ieunj01Iew,11788
 polydb/adapters/PostgreSQLAdapter.py,sha256=9VI4-JOdDPeCDba8lRar4RkVMuF0bAymkvSTE3HILjs,38239
 polydb/adapters/S3Adapter.py,sha256=5R0zHAL2SkGFjp1L3bp-IU468bXYdSf6nKx974MN104,7586
 polydb/adapters/S3CompatibleAdapter.py,sha256=jpafqbAjA8-irdXBrfXa1QJySIzrcUQ6UrFt5h5FAEc,7006
@@ -45,11 +45,11 @@ polydb/adapters/VercelFileAdapter.py,sha256=-fLRCi0AUbyXAR4nkHCV-wXkociHF2hzzEDq
 polydb/adapters/VercelKVAdapter.py,sha256=QZxRkuYzVNWFCEFaJPSph8YEAut-YtlXPqbCt0JlROI,8647
 polydb/adapters/VercelQueueAdapter.py,sha256=cWtPaMIWCako0HHr_rzAE6vMLugSR6zBXqp3VP9MXwY,2375
 polydb/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-polydb/audit/AuditStorage.py,sha256=7HBEN6m-tBWVJJXxXIe13pe4SMi2BxncPm-_MNPgwNw,6455
+polydb/audit/AuditStorage.py,sha256=6luCS7hTNL5MH2kkn6QlBlBsH-3FLuEFwP-cmkugRss,10469
 polydb/audit/__init__.py,sha256=Z7-y5djq3glQ2Yun6nj-13Efpj3oGz9Qc0veS2g06Y4,245
 polydb/audit/context.py,sha256=-A1FMtmr-2snVAHpTrVT80u-D_MCaqX6AoV4Ku2bz_o,1955
 polydb/audit/manager.py,sha256=KzaaOf5bDfr4M-CkCAZBG_U_4xIBCKDLRAf3hsm-DAk,1236
-polydb/audit/models.py,sha256=NapdH5dXU9GMoP9ccbDFaeMWvWbwoh2B5N7Nd3Ci6Cg,3745
+polydb/audit/models.py,sha256=cSDkzW22FnsMvjQFvLQACQUm9lYFcnJ2Ew5mngBF9yQ,7043
 polydb/base/NoSQLKVAdapter.py,sha256=U64nXaeHd40GCZV4DQnogZRUxvI8HHLEhNBMv4oddq4,14491
 polydb/base/ObjectStorageAdapter.py,sha256=VeJ3qXET6H0xd3lJpE8-WSsKs8EyK9S0-9VNR0EJzME,2288
 polydb/base/QueueAdapter.py,sha256=jFgyG-SUK4nhRNxm2NbzUbwnA9b_5iAC-ikLSUpXRwk,799
@@ -60,7 +60,7 @@ polydb/observability/logging.py,sha256=gv1SshNjaSkmR98Uv7Qbwq3gkeQUzVCA4ichqHKL6
 polydb/services/__init__.py,sha256=nMolMXzmhejRSm7f42kU9fCHF0GIpqpejN2kywuBsUQ,241
 polydb/services/compliance_service.py,sha256=-0ncX7PrXy4-NuyWXIv65cLUsqz0jXzb3LtsD8rlrXE,4983
 polydb/services/security_service.py,sha256=q7GzK6sbMnBBsc4fuL4oXTd-ui2b-MYQyrWTBvdVNSk,5062
-altcodepro_polydb_python-2.3.31.dist-info/METADATA,sha256=mEh53S4z1JD9K0ZMj4b4L1EOPOZji-fSz4vCS5BHCjQ,12359
-altcodepro_polydb_python-2.3.31.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-altcodepro_polydb_python-2.3.31.dist-info/top_level.txt,sha256=WgLFWJoYjUhwvyPxJFl6jYLrVFuBJDX3OABf4ocwk_E,7
-altcodepro_polydb_python-2.3.31.dist-info/RECORD,,
+altcodepro_polydb_python-2.5.2.dist-info/METADATA,sha256=sto5LPHuXLzUHq-h5cuH6g6IaF1DhTo0s_y1o0xidOs,12492
+altcodepro_polydb_python-2.5.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+altcodepro_polydb_python-2.5.2.dist-info/top_level.txt,sha256=WgLFWJoYjUhwvyPxJFl6jYLrVFuBJDX3OABf4ocwk_E,7
+altcodepro_polydb_python-2.5.2.dist-info/RECORD,,

{altcodepro_polydb_python-2.3.31.dist-info → altcodepro_polydb_python-2.5.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (83.0.0)
+Generator: setuptools (84.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

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,73 @@ 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)
+
+    # -----------------------------------------------------
+    # Internal <-> domain field mapping
+    # -----------------------------------------------------
+
+    def _finalize_doc(self, model: type, doc: JsonDict) -> JsonDict:
+        """
+        Strip PolyDB's internal _pk/_rk storage keys before returning a
+        record, mapping each back to the domain field it was derived from
+        (the model's declared partition_key/sort_key) -- mirrors
+        AzureTableStorageAdapter._unpack_entity, which already does this
+        for PartitionKey/RowKey. Without it, callers see raw storage-
+        internal column names instead of their own schema's field names.
+        Guarded with setdefault so a real stored property never gets
+        clobbered by the derived value.
+        """
+        pk_field, rk_field = self._pk_rk_field_names(model)
+        pk_val = doc.pop("_pk", None)
+        rk_val = doc.pop("_rk", None)
+
+        if pk_val is not None:
+            doc.setdefault(pk_field, pk_val)
+        if rk_val is not None:
+            doc.setdefault(rk_field, rk_val)
+
+        doc.setdefault("id", rk_val)
+
+        return doc
 
     # -----------------------------------------------------
     # PUT
@@ -87,7 +173,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},
@@ -96,11 +186,7 @@ class MongoDBAdapter(NoSQLKVAdapter):
             )
 
             # return full stored row (tests expect this)
-            result = dict(payload)
-            result.pop("_pk", None)
-            result.pop("_rk", None)
-
-            return result
+            return self._finalize_doc(model, dict(payload))
 
         except Exception as e:
             raise NoSQLError(f"MongoDB put failed: {e}")
@@ -120,9 +206,8 @@ class MongoDBAdapter(NoSQLKVAdapter):
                 return None
 
             doc.pop("_id", None)
-            doc.setdefault("id", pk)
 
-            return doc
+            return self._finalize_doc(model, doc)
 
         except Exception as e:
             raise NoSQLError(f"MongoDB get failed: {e}")
@@ -140,7 +225,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,8 +238,7 @@ class MongoDBAdapter(NoSQLKVAdapter):
 
             for doc in cursor:
                 doc.pop("_id", None)
-                doc.setdefault("id", doc.get("_pk"))
-                rows.append(doc)
+                rows.append(self._finalize_doc(model, doc))
 
             if not rows:
                 return [], None
@@ -179,7 +265,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 +281,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 +294,7 @@ class MongoDBAdapter(NoSQLKVAdapter):
                     }
 
                 else:
-                    query[k] = v
+                    query[k] = _as_literal(v)
 
             cursor = collection.find(query)
 
@@ -216,8 +305,7 @@ class MongoDBAdapter(NoSQLKVAdapter):
 
             for doc in cursor:
                 doc.pop("_id", None)
-                doc.setdefault("id", doc.get("_pk"))
-                results.append(doc)
+                results.append(self._finalize_doc(model, doc))
 
             return results
 
@@ -238,7 +326,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

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
 

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

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

polydb/errors.py

@@ -86,3 +86,9 @@ class InsufficientBalanceError(PolyDBError):
     """Raised when an atomic decrement is attempted but the balance is insufficient."""
 
     pass
+
+
+class EncryptionConfigError(PolyDBError):
+    """Raised when field encryption is requested but no usable key is configured."""
+
+    pass

polydb/multitenancy.py

@@ -2,11 +2,43 @@
 """
 Multi-tenancy enforcement and isolation
 """
+import re
 from typing import Dict, Any, List, Optional, Callable
 from contextvars import ContextVar
 from dataclasses import dataclass, field
 from enum import Enum
 
+from .errors import ValidationError
+
+# Schema/database names get interpolated into DDL, which cannot be
+# parameterised - a bind parameter is a *value*, and these are identifiers.
+# So they need the same allowlist the SQL adapter already applies to every
+# table and column name via utils.validate_table_name. These DDL paths were
+# the one place that skipped it.
+_SQL_IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+#: Longest identifier PostgreSQL accepts.
+_MAX_IDENTIFIER_LENGTH = 63
+
+
+def _validate_sql_identifier(value: str, *, kind: str) -> str:
+    """Allowlist a schema/database name before it is spliced into DDL.
+
+    Rejects anything that is not a bare identifier, so a tenant-derived name
+    such as ``x; DROP SCHEMA public CASCADE; --`` can never reach the database.
+    """
+    if not isinstance(value, str) or not value:
+        raise ValidationError(f"Invalid {kind}: {value!r} (must be a non-empty string)")
+    if len(value) > _MAX_IDENTIFIER_LENGTH:
+        raise ValidationError(
+            f"Invalid {kind}: {value!r} exceeds {_MAX_IDENTIFIER_LENGTH} characters"
+        )
+    if not _SQL_IDENTIFIER_RE.match(value):
+        raise ValidationError(
+            f"Invalid {kind}: {value!r}. Only letters, digits and underscores are "
+            "allowed, and it may not start with a digit."
+        )
+    return value
+
 
 class IsolationLevel(Enum):
     """Tenant isolation levels"""
@@ -172,12 +204,16 @@ class TenantMigrationManager:
         
         if config.isolation_level == IsolationLevel.SEPARATE_SCHEMA:
             # Create schema
-            schema_sql = f"CREATE SCHEMA IF NOT EXISTS {config.schema_name};"
+            schema = _validate_sql_identifier(config.schema_name, kind="schema_name")
+            schema_sql = f"CREATE SCHEMA IF NOT EXISTS {schema};"
             self.factory._sql.execute(schema_sql)
         
         elif config.isolation_level == IsolationLevel.SEPARATE_DATABASE:
             # Create database (requires superuser)
-            db_sql = f"CREATE DATABASE {config.database_name};"
+            database = _validate_sql_identifier(
+                config.database_name, kind="database_name"
+            )
+            db_sql = f"CREATE DATABASE {database};"
             self.factory._sql.execute(db_sql)
     
     def deprovision_tenant(self, tenant_id: str):
@@ -188,10 +224,14 @@ class TenantMigrationManager:
         
         if config.isolation_level == IsolationLevel.SEPARATE_SCHEMA:
             # Drop schema
-            schema_sql = f"DROP SCHEMA IF EXISTS {config.schema_name} CASCADE;"
+            schema = _validate_sql_identifier(config.schema_name, kind="schema_name")
+            schema_sql = f"DROP SCHEMA IF EXISTS {schema} CASCADE;"
             self.factory._sql.execute(schema_sql)
         
         elif config.isolation_level == IsolationLevel.SEPARATE_DATABASE:
             # Drop database
-            db_sql = f"DROP DATABASE IF EXISTS {config.database_name};"
+            database = _validate_sql_identifier(
+                config.database_name, kind="database_name"
+            )
+            db_sql = f"DROP DATABASE IF EXISTS {database};"
             self.factory._sql.execute(db_sql)

polydb/query.py

@@ -2,10 +2,48 @@
 
 from __future__ import annotations
 from dataclasses import dataclass, field
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Mapping, Optional, Union
 from enum import Enum
+from .errors import ValidationError
 from .utils import validate_column_name
 
+#: Escape character used for LIKE patterns built from user values.
+LIKE_ESCAPE_CHAR = "\\"
+
+
+def _escape_like(value: Any) -> str:
+    """Neutralise LIKE metacharacters in a value before it is wrapped in wildcards.
+
+    ``CONTAINS``/``STARTS_WITH``/``ENDS_WITH`` mean "this literal substring".
+    The value is bound as a parameter (so there is no SQL injection here), but
+    an unescaped ``%`` or ``_`` in it is still interpreted by the pattern
+    matcher: it silently widens the match, and a leading ``%`` turns an
+    index-friendly prefix scan into a full scan.
+    """
+    text = str(value)
+    for char in (LIKE_ESCAPE_CHAR, "%", "_"):
+        text = text.replace(char, LIKE_ESCAPE_CHAR + char)
+    return text
+
+
+def _reject_mapping_value(f: "QueryFilter") -> None:
+    """Refuse dict filter values on the NoSQL path.
+
+    A document store reads a dict on the right-hand side of a field as an
+    operator expression, so a filter value that reaches here straight from
+    request input - ``where("password", EQ, {"$gt": ""})`` - stops being a
+    comparison and becomes "any document with a password", i.e. auth bypass
+    plus full-collection extraction. Nothing goes through QueryBuilder with a
+    legitimate dict value; lists stay allowed because ``IN`` needs them (and a
+    list can never be read as an operator).
+    """
+    values = f.value if isinstance(f.value, (list, tuple, set)) else [f.value]
+    if isinstance(f.value, Mapping) or any(isinstance(v, Mapping) for v in values):
+        raise ValidationError(
+            f"Invalid filter value for '{f.field}': dict values are not allowed "
+            "in NoSQL filters (they would be interpreted as query operators)."
+        )
+
 
 class Operator(Enum):
     EQ = "=="
@@ -175,16 +213,16 @@ class QueryBuilder:
                 params.extend(f.value)
 
             elif f.operator == Operator.CONTAINS:
-                clauses.append(f"{f.field} LIKE %s")
-                params.append(f"%{f.value}%")
+                clauses.append(f"{f.field} LIKE %s ESCAPE '{LIKE_ESCAPE_CHAR}'")
+                params.append(f"%{_escape_like(f.value)}%")
 
             elif f.operator == Operator.STARTS_WITH:
-                clauses.append(f"{f.field} LIKE %s")
-                params.append(f"{f.value}%")
+                clauses.append(f"{f.field} LIKE %s ESCAPE '{LIKE_ESCAPE_CHAR}'")
+                params.append(f"{_escape_like(f.value)}%")
 
             elif f.operator == Operator.ENDS_WITH:
-                clauses.append(f"{f.field} LIKE %s")
-                params.append(f"%{f.value}")
+                clauses.append(f"{f.field} LIKE %s ESCAPE '{LIKE_ESCAPE_CHAR}'")
+                params.append(f"%{_escape_like(f.value)}")
 
         return " AND ".join(clauses), params
 
@@ -197,6 +235,7 @@ class QueryBuilder:
         result = {}
 
         for f in self.filters:
+            _reject_mapping_value(f)
 
             if f.operator == Operator.EQ:
                 result[f.field] = f.value

polydb/schema.py

@@ -4,10 +4,33 @@ Schema management and migrations
 """
 from typing import Dict, List, Optional, Any
 from dataclasses import dataclass
+from decimal import Decimal
 from enum import Enum
 import json
 from datetime import datetime
 
+from .errors import ValidationError
+from .utils import validate_column_name, validate_table_name
+
+
+def _render_default(value: Any) -> str:
+    """Render a column DEFAULT as a literal that cannot escape its context.
+
+    A string default used to be interpolated as ``DEFAULT '{value}'``, so a
+    single quote in it closed the literal and the rest of the value was parsed
+    as SQL - the whole statement is DDL, which cannot be parameterised, so the
+    literal has to be made safe here. Quotes are doubled (the SQL-standard
+    escape); numbers and booleans keep rendering bare as before.
+    """
+    if isinstance(value, bool) or isinstance(value, (int, float, Decimal)):
+        return f"DEFAULT {value}"
+
+    text = str(value)
+    if "\x00" in text:
+        raise ValidationError("Invalid column default: NUL characters are not allowed")
+    escaped = text.replace("'", "''")
+    return f"DEFAULT '{escaped}'"
+
 
 class ColumnType(Enum):
     INTEGER = "INTEGER"
@@ -61,10 +84,11 @@ class SchemaBuilder:
     
     def to_create_table(self, table_name: str) -> str:
         """Generate CREATE TABLE statement"""
+        validate_table_name(table_name)
         col_defs = []
-        
+
         for col in self.columns:
-            parts = [col.name]
+            parts = [validate_column_name(col.name)]
             
             # Type
             if col.type == ColumnType.VARCHAR and col.max_length:
@@ -78,10 +102,7 @@ class SchemaBuilder:
             
             # Default
             if col.default is not None:
-                if isinstance(col.default, str):
-                    parts.append(f"DEFAULT '{col.default}'")
-                else:
-                    parts.append(f"DEFAULT {col.default}")
+                parts.append(_render_default(col.default))
             
             # Unique
             if col.unique:
@@ -91,7 +112,8 @@ class SchemaBuilder:
         
         # Primary key
         if self.primary_keys:
-            col_defs.append(f"PRIMARY KEY ({', '.join(self.primary_keys)})")
+            pk_cols = [validate_column_name(c) for c in self.primary_keys]
+            col_defs.append(f"PRIMARY KEY ({', '.join(pk_cols)})")
         
         sql = f"CREATE TABLE IF NOT EXISTS {table_name} (\n"
         sql += ",\n".join(f"  {col}" for col in col_defs)
@@ -103,10 +125,15 @@ class SchemaBuilder:
         """Generate CREATE INDEX statements"""
         statements = []
         
+        validate_table_name(table_name)
+
         for idx in self.indexes:
             unique = "UNIQUE " if idx.unique else ""
-            cols = ", ".join(idx.columns)
-            sql = f"CREATE {unique}INDEX IF NOT EXISTS {idx.name} ON {table_name}({cols});"
+            cols = ", ".join(validate_column_name(c) for c in idx.columns)
+            sql = (
+                f"CREATE {unique}INDEX IF NOT EXISTS {validate_table_name(idx.name)} "
+                f"ON {table_name}({cols});"
+            )
             statements.append(sql)
         
         return statements

polydb/security.py

@@ -13,9 +13,12 @@ from functools import wraps
 import logging
 
 from .json_safe import json_safe
+from .errors import EncryptionConfigError
 
 logger = logging.getLogger(__name__)
 
+DEFAULT_KEY_ID = "v1"
+
 
 @dataclass
 class EncryptionConfig:
@@ -27,60 +30,138 @@ class EncryptionConfig:
 
 
 class FieldEncryption:
-    """Field-level encryption for sensitive data"""
+    """Field-level encryption for sensitive data (AES-256-GCM).
+
+    Keys are loaded from the environment - never generated in memory - so a
+    process restart can never silently orphan previously-encrypted data:
+
+    - ``POLYDB_ENCRYPTION_KEY``: base64-encoded 32-byte key used to encrypt
+      new values. Its key id is ``POLYDB_ENCRYPTION_KEY_ID`` (default "v1").
+    - ``POLYDB_ENCRYPTION_KEYS``: optional JSON object ``{key_id: base64key}``
+      of retired keys kept around only to decrypt values written before a
+      rotation; not used for new encryption.
+
+    Constructing this class raises :class:`EncryptionConfigError` if no
+    active key is configured - callers only instantiate it when encryption
+    is explicitly enabled, so failing fast here means a misconfigured
+    deployment refuses to start rather than persisting plaintext.
+    """
 
     def __init__(self, encryption_key: Optional[bytes] = None):
-        self.encryption_key = encryption_key or self._generate_key()
+        if encryption_key is not None:
+            self._keys: Dict[str, bytes] = {DEFAULT_KEY_ID: encryption_key}
+            self._active_key_id = DEFAULT_KEY_ID
+        else:
+            self._keys = self._load_keys()
+            self._active_key_id = os.getenv("POLYDB_ENCRYPTION_KEY_ID", DEFAULT_KEY_ID).strip()
+            if self._active_key_id not in self._keys:
+                raise EncryptionConfigError(
+                    f"POLYDB_ENCRYPTION_KEY_ID={self._active_key_id!r} has no matching key. "
+                    "Set POLYDB_ENCRYPTION_KEY (for the active key id) or include it in "
+                    "POLYDB_ENCRYPTION_KEYS."
+                )
+
+    @property
+    def encryption_key(self) -> bytes:
+        """The active key's raw bytes (kept for backward-compatible access)."""
+        return self._keys[self._active_key_id]
 
     @staticmethod
-    def _generate_key() -> bytes:
-        """Generate encryption key from environment or create new"""
-        key_str = os.getenv("POLYDB_ENCRYPTION_KEY")
-        if key_str:
-            return base64.b64decode(key_str)
-
-        # Generate new key (should be saved securely)
-        key = os.urandom(32)
-        # For production, log or store this key securely; here we just warn
-        logger.warning(
-            "Generated new encryption key. Store it securely in POLYDB_ENCRYPTION_KEY env var."
-        )
+    def _decode_key(raw: str, source: str) -> bytes:
+        try:
+            key = base64.b64decode(raw, validate=True)
+        except Exception as exc:
+            raise EncryptionConfigError(f"{source} is not valid base64: {exc}") from exc
+        if len(key) != 32:
+            raise EncryptionConfigError(
+                f"{source} decodes to {len(key)} bytes; AES-256-GCM requires exactly 32 bytes."
+            )
         return key
 
+    @classmethod
+    def _load_keys(cls) -> Dict[str, bytes]:
+        """Load the active key plus any retired keys from the environment."""
+        keys: Dict[str, bytes] = {}
+
+        retired_raw = os.getenv("POLYDB_ENCRYPTION_KEYS")
+        if retired_raw:
+            try:
+                retired = json.loads(retired_raw)
+            except json.JSONDecodeError as exc:
+                raise EncryptionConfigError(
+                    f"POLYDB_ENCRYPTION_KEYS is not valid JSON: {exc}"
+                ) from exc
+            for key_id, raw in retired.items():
+                keys[key_id] = cls._decode_key(raw, f"POLYDB_ENCRYPTION_KEYS[{key_id!r}]")
+
+        active_raw = os.getenv("POLYDB_ENCRYPTION_KEY")
+        if not active_raw:
+            raise EncryptionConfigError(
+                "Field encryption is enabled but POLYDB_ENCRYPTION_KEY is not set. "
+                "Generate one with: python -c \"import os,base64; "
+                "print(base64.b64encode(os.urandom(32)).decode())\" and store it securely "
+                "(e.g. Azure Key Vault / AWS Secrets Manager / GCP Secret Manager) - do not "
+                "commit it or let it be generated on the fly."
+            )
+        active_key_id = os.getenv("POLYDB_ENCRYPTION_KEY_ID", DEFAULT_KEY_ID).strip()
+        keys[active_key_id] = cls._decode_key(active_raw, "POLYDB_ENCRYPTION_KEY")
+        return keys
+
     def _encrypt_value(self, value: Any) -> str:
         """Encrypt arbitrary value (serialize if non-str)"""
         if value is None:
             return ""
         data = json.dumps(value, default=json_safe) if not isinstance(value, str) else value
+
         try:
             from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+        except ImportError as exc:
+            raise ImportError(
+                "cryptography not installed. Install with: pip install 'altcodepro-polydb-python[security]'"
+            ) from exc
 
-            aesgcm = AESGCM(self.encryption_key)
-            nonce = os.urandom(12)
+        aesgcm = AESGCM(self._keys[self._active_key_id])
+        nonce = os.urandom(12)
 
-            ciphertext = aesgcm.encrypt(nonce, data.encode("utf-8"), None)
+        ciphertext = aesgcm.encrypt(nonce, data.encode("utf-8"), None)
 
-            # Combine nonce and ciphertext
-            encrypted = base64.b64encode(nonce + ciphertext).decode("utf-8")
-            return f"encrypted:{encrypted}"
-        except ImportError:
-            raise ImportError("cryptography not installed. Install with: pip install cryptography")
+        # Combine nonce and ciphertext; tag the payload with the key id used so a
+        # future key rotation can still decrypt values written under an older key.
+        encrypted = base64.b64encode(nonce + ciphertext).decode("utf-8")
+        return f"encrypted:{self._active_key_id}:{encrypted}"
 
     def _decrypt_value(self, encrypted_data: Any) -> Any:
         """Decrypt field data (deserialize if needed)"""
         if not isinstance(encrypted_data, str) or not encrypted_data.startswith("encrypted:"):
             return encrypted_data
 
-        try:
-            from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+        payload = encrypted_data[len("encrypted:"):]
+        # Legacy format (pre key-versioning) has no key id segment - decrypt
+        # with the active key for backward compatibility with existing data.
+        key_id, _, b64_blob = payload.partition(":")
+        if not b64_blob:
+            key_id, b64_blob = self._active_key_id, key_id
 
-            encrypted_data = encrypted_data[10:]  # Remove prefix
-            combined = base64.b64decode(encrypted_data)
+        key = self._keys.get(key_id)
+        if key is None:
+            raise EncryptionConfigError(
+                f"No encryption key available for key id {key_id!r}. Add it to "
+                "POLYDB_ENCRYPTION_KEYS to decrypt values written before a key rotation."
+            )
+
+        try:
+            try:
+                from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+            except ImportError as exc:
+                raise ImportError(
+                    "cryptography not installed. Install with: pip install 'altcodepro-polydb-python[security]'"
+                ) from exc
 
+            combined = base64.b64decode(b64_blob)
             nonce = combined[:12]
             ciphertext = combined[12:]
 
-            aesgcm = AESGCM(self.encryption_key)
+            aesgcm = AESGCM(key)
             plaintext_bytes = aesgcm.decrypt(nonce, ciphertext, None)
             plaintext = plaintext_bytes.decode("utf-8")
 
@@ -89,8 +170,6 @@ class FieldEncryption:
                 return json.loads(plaintext)
             except json.JSONDecodeError:
                 return plaintext
-        except ImportError:
-            raise ImportError("cryptography not installed")
         except Exception as e:
             # Fail loud. Returning ciphertext as if it were plaintext masks
             # key-rotation errors / corruption and leaks the 'encrypted:' blob