matrx-orm 3.1.184__tar.gz → 3.1.185__tar.gz

{matrx_orm-3.1.184 → matrx_orm-3.1.185}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.184
+Version: 3.1.185
 Summary: Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching
 Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
 Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current

{matrx_orm-3.1.184 → matrx_orm-3.1.185}/matrx_orm/secrets_battery/backup_restore.py

@@ -70,6 +70,7 @@ class BackupHistoryRevisionSpec:
 
     revision: int
     value: str
+    source_recorded_at: datetime | None = None
 
 
 @asynccontextmanager
@@ -271,6 +272,14 @@ def _validate_history(
             or type(revision.revision) is not int
             or revision.revision != expected
             or not isinstance(revision.value, str)
+            or (
+                revision.source_recorded_at is not None
+                and (
+                    not isinstance(revision.source_recorded_at, datetime)
+                    or revision.source_recorded_at.tzinfo is None
+                    or revision.source_recorded_at.utcoffset() is None
+                )
+            )
         ):
             raise ValueError("backup history is invalid")
         checked.append(revision)
@@ -328,6 +337,7 @@ async def _write_quarantined_history(
             before_encrypted=current,
             after_encrypted=after,
             capture_started_at=started,
+            source_recorded_at=revision.source_recorded_at,
         )
         expected_revision = await write_password_field_update_snapshot(
             item_id=item_id,

{matrx_orm-3.1.184 → matrx_orm-3.1.185}/matrx_orm/secrets_battery/vault_history.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import re
 import uuid
 from datetime import UTC, datetime
+from math import isfinite
 from typing import Any
 
 from matrx_orm import call_function
@@ -22,6 +23,7 @@ _ENVELOPE_KEYS = {
     "schema_version", "snapshot_id", "mutation_kind", "original_ownership",
     "audit_organization_id", "capture_started_at", "component_manifest", "changed_components",
 }
+_ENVELOPE_KEYS_WITH_SOURCE_RECORDED_AT = _ENVELOPE_KEYS | {"source_recorded_at"}
 
 
 class VaultHistorySnapshotError(ValueError):
@@ -44,10 +46,21 @@ def _state(value_encrypted: Any, key_fingerprint: str) -> dict[str, str]:
     return {"value_encrypted": _ciphertext(value_encrypted), "key_fingerprint": key_fingerprint}
 
 
+def _source_recorded_at(value: datetime) -> str:
+    if not isinstance(value, datetime) or value.tzinfo is None or value.utcoffset() is None:
+        raise VaultHistorySnapshotError("Vault history source timestamp must be timezone-aware")
+    try:
+        if not isfinite(value.timestamp()):
+            raise ValueError
+    except (OverflowError, OSError, ValueError) as exc:
+        raise VaultHistorySnapshotError("Vault history source timestamp must be finite") from exc
+    return value.astimezone(UTC).isoformat()
+
+
 def password_field_update_snapshot(
     *, item_id: str, item_user_id: str, audit_organization_id: str, field_id: str,
     field_key: str, handling: str, execution_purpose: str, before_encrypted: Any,
-    after_encrypted: Any, capture_started_at: datetime,
+    after_encrypted: Any, capture_started_at: datetime, source_recorded_at: datetime | None = None,
 ) -> dict[str, Any]:
     """Build the only Gate-B shape accepted for an ordinary password update."""
     if field_key != "password" or handling not in {"visible", "revealable"} or execution_purpose != "general":
@@ -79,13 +92,18 @@ def password_field_update_snapshot(
         "component_manifest": [manifest],
         "changed_components": [change],
     }
+    if source_recorded_at is not None:
+        snapshot["source_recorded_at"] = _source_recorded_at(source_recorded_at)
     validate_snapshot_v1(snapshot)
     return snapshot
 
 
 def validate_snapshot_v1(snapshot: dict[str, Any]) -> None:
     """Reject accidental plaintext, hints, unknown keys, and incomplete v1 states."""
-    if set(snapshot) != _ENVELOPE_KEYS or snapshot.get("schema_version") != 1 or snapshot.get("mutation_kind") != "update":
+    if (
+        set(snapshot) != _ENVELOPE_KEYS
+        and set(snapshot) != _ENVELOPE_KEYS_WITH_SOURCE_RECORDED_AT
+    ) or snapshot.get("schema_version") != 1 or snapshot.get("mutation_kind") != "update":
         raise VaultHistorySnapshotError("Vault history snapshot is not the closed v1 envelope")
     try:
         uuid.UUID(str(snapshot["snapshot_id"]))
@@ -96,6 +114,11 @@ def validate_snapshot_v1(snapshot: dict[str, Any]) -> None:
         raise VaultHistorySnapshotError("Vault history snapshot has invalid identity data") from exc
     if set(snapshot["original_ownership"]) != {"user_id"}:
         raise VaultHistorySnapshotError("Vault history snapshot must have one personal owner")
+    if "source_recorded_at" in snapshot:
+        try:
+            _source_recorded_at(datetime.fromisoformat(str(snapshot["source_recorded_at"]).replace("Z", "+00:00")))
+        except (TypeError, ValueError) as exc:
+            raise VaultHistorySnapshotError("Vault history source timestamp is invalid") from exc
     manifest = snapshot["component_manifest"]
     changes = snapshot["changed_components"]
     if not isinstance(manifest, list) or len(manifest) != 1 or not isinstance(changes, list) or len(changes) != 1:

{matrx_orm-3.1.184 → matrx_orm-3.1.185}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.184"
+version = "3.1.185"
 description = "Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching"
 readme = "README.md"
 license = { text = "MIT" }

{matrx_orm-3.1.184 → matrx_orm-3.1.185}/tests/test_backup_history_restore.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from types import SimpleNamespace
+from datetime import UTC, datetime
 
 import pytest
 
@@ -36,6 +37,14 @@ def test_history_allows_a_same_plaintext_delta_when_the_source_ciphertext_rotate
     assert len(result) == 2
 
 
+def test_history_carries_an_aware_source_timestamp_without_using_it_for_ordering():
+    result = _validate_history(
+        [BackupHistoryRevisionSpec(1, "current", datetime(2040, 1, 1, tzinfo=UTC))],
+        _password(),
+    )
+    assert result[0].source_recorded_at == datetime(2040, 1, 1, tzinfo=UTC)
+
+
 @pytest.mark.parametrize(
     ("history", "fields"),
     [
@@ -124,6 +133,12 @@ async def test_same_plaintext_delta_is_written_with_fresh_destination_ciphertext
         actor_id="33333333-3333-4333-8333-333333333333",
         audit_organization_id="44444444-4444-4444-8444-444444444444",
         handling="revealable",
-        history=(_revision(1, "same"), _revision(2, "same")),
+        history=(
+            BackupHistoryRevisionSpec(1, "same", datetime(2020, 1, 1, tzinfo=UTC)),
+            BackupHistoryRevisionSpec(2, "same", datetime(2020, 1, 2, tzinfo=UTC)),
+        ),
     )
     assert snapshots[1]["changed_components"][0]["before"] != snapshots[1]["changed_components"][0]["after"]
+    assert [snapshot["source_recorded_at"] for snapshot in snapshots] == [
+        "2020-01-01T00:00:00+00:00", "2020-01-02T00:00:00+00:00"
+    ]

{matrx_orm-3.1.184 → matrx_orm-3.1.185}/tests/test_secrets_battery.py

@@ -1177,6 +1177,30 @@ def test_password_history_snapshot_v1_excludes_plaintext_and_hints(monkeypatch):
         vault_history.validate_snapshot_v1(snapshot)
 
 
+def test_password_history_snapshot_v1_accepts_only_a_valid_optional_source_timestamp(monkeypatch):
+    from matrx_orm.secrets_battery import vault_history
+
+    monkeypatch.setenv("CREDENTIALS_ENCRYPTION_KEY", _fernet_key())
+    snapshot = vault_history.password_field_update_snapshot(
+        item_id="00000000-0000-0000-0000-000000000001",
+        item_user_id="00000000-0000-0000-0000-000000000002",
+        audit_organization_id="00000000-0000-0000-0000-000000000003",
+        field_id="00000000-0000-0000-0000-000000000004",
+        field_key="password", handling="revealable", execution_purpose="general",
+        before_encrypted=_history_ciphertext(), after_encrypted=_history_ciphertext(),
+        capture_started_at=datetime.now(UTC), source_recorded_at=datetime(2040, 1, 2, tzinfo=UTC),
+    )
+    assert set(snapshot) == {
+        "schema_version", "snapshot_id", "mutation_kind", "original_ownership",
+        "audit_organization_id", "capture_started_at", "source_recorded_at",
+        "component_manifest", "changed_components",
+    }
+    assert snapshot["source_recorded_at"] == "2040-01-02T00:00:00+00:00"
+    snapshot["source_recorded_at"] = "2040-01-02T00:00:00"
+    with pytest.raises(vault_history.VaultHistorySnapshotError, match="source timestamp"):
+        vault_history.validate_snapshot_v1(snapshot)
+
+
 def _history_update_fakes(
     monkeypatch, *, writer_error: Exception | None = None, writer_error_call: int | None = None,
     revision: int = 0,