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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.183
+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
@@ -26,7 +26,7 @@ Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: cbor2<7,>=6.1.3
 Requires-Dist: cryptography>=43.0
 Requires-Dist: gitpython>=3.1.40
-Requires-Dist: matrx-utils>=2.0.54
+Requires-Dist: matrx-utils>=2.0.55
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

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

@@ -5,6 +5,7 @@ from __future__ import annotations
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
+from datetime import UTC, datetime
 from typing import Literal
 from uuid import UUID
 
@@ -34,6 +35,11 @@ from .mutation_receipts import (
     reserve_backup_restore_receipt,
 )
 from .org_service import record_secret_audit
+from .vault_history import (
+    locked_history_revision,
+    password_field_update_snapshot,
+    write_password_field_update_snapshot,
+)
 
 
 @dataclass(frozen=True, repr=False)
@@ -58,6 +64,15 @@ class BackupRestoreAliasConflictError(Exception):
     """A restored alias is reserved; the entire record was rolled back."""
 
 
+@dataclass(frozen=True, repr=False)
+class BackupHistoryRevisionSpec:
+    """One portable password state; source ciphertext never enters this boundary."""
+
+    revision: int
+    value: str
+    source_recorded_at: datetime | None = None
+
+
 @asynccontextmanager
 async def _restore_transaction() -> AsyncIterator[None]:
     try:
@@ -91,6 +106,7 @@ async def create_backup_record_quarantined(
     non_secret_fields: list[dict[str, str]],
     fields: list[FieldSpec],
     attachments: list[BackupAttachmentSpec],
+    history: list[BackupHistoryRevisionSpec] | None = None,
 ) -> BackupRestoreResult:
     """Restore one host-authorized personal aggregate and receipt in one transaction."""
     # The host supplies verified actor/context and computes the binding fingerprint.
@@ -114,6 +130,7 @@ async def create_backup_record_quarantined(
         # Validation is shared, but restoration must not silently normalize source text.
         metadata["login_urls"] = login_urls
         seen: set[str] = set()
+        password_fields: list[FieldSpec] = []
         for field in fields:
             _validate_field_key(field.field_key)
             _refuse_reserved_generic_field(field.field_key)
@@ -123,6 +140,8 @@ async def create_backup_record_quarantined(
                 raise ValueError("backup field is not portable")
             if field.inject_into_sandbox:
                 raise ValueError("backup cannot enable sandbox injection")
+            if field.field_key == "password":
+                password_fields.append(field)
             seen.add(field.field_key)
         for attachment in attachments:
             if attachment.source_handling not in {"visible", "revealable"}:
@@ -133,6 +152,7 @@ async def create_backup_record_quarantined(
             _validate_text(attachment.media_type, name="attachment media type", maximum=255)
             if attachment.description is not None and len(attachment.description) > 2000:
                 raise ValueError("attachment description is too long")
+        history = _validate_history(history, password_fields)
     except (TypeError, ValueError, AttributeError):
         raise ValueError("Invalid backup restore record.") from None
 
@@ -165,8 +185,9 @@ async def create_backup_record_quarantined(
             created_by=actor_id,
             updated_by=actor_id,
         )
+        password_row: UserSecret | None = None
         for field in fields:
-            await UserSecret.create(
+            created = await UserSecret.create(
                 user_id=actor_id,
                 organization_id=None,
                 credential_item_id=item.id,
@@ -184,6 +205,22 @@ async def create_backup_record_quarantined(
                 created_by=actor_id,
                 updated_by=actor_id,
             )
+            if field.field_key == "password":
+                password_row = created
+        if history:
+            # The private writer deliberately requires an active field and an
+            # active snapshot manifest.  This activation is transaction-local:
+            # the item remains disabled, no grant is created, and the field is
+            # made inactive again before the receipt can commit.
+            assert password_row is not None
+            await _write_quarantined_history(
+                item_id=str(item.id),
+                field_id=str(password_row.id),
+                actor_id=actor_id,
+                audit_organization_id=audit_organization_id,
+                handling=password_fields[0].handling,
+                history=history,
+            )
         for attachment in attachments:
             await CredentialAttachment.create(
                 credential_item_id=item.id,
@@ -215,6 +252,111 @@ async def create_backup_record_quarantined(
         return BackupRestoreResult(str(item.id), False)
 
 
+def _validate_history(
+    history: list[BackupHistoryRevisionSpec] | None,
+    password_fields: list[FieldSpec],
+) -> tuple[BackupHistoryRevisionSpec, ...]:
+    """Refuse an incomplete portable chain before any restore row is inserted."""
+    if history is None:
+        return ()
+    if not isinstance(history, list):
+        raise ValueError("backup history is invalid")
+    if not history:
+        return ()
+    if len(password_fields) != 1 or password_fields[0].handling not in {"visible", "revealable"}:
+        raise ValueError("backup history requires one ordinary password field")
+    checked: list[BackupHistoryRevisionSpec] = []
+    for expected, revision in enumerate(history, start=1):
+        if (
+            not isinstance(revision, BackupHistoryRevisionSpec)
+            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)
+    if checked[-1].value != password_fields[0].value:
+        raise ValueError("backup history does not match the current password")
+    return tuple(checked)
+
+
+async def _write_quarantined_history(
+    *,
+    item_id: str,
+    field_id: str,
+    actor_id: str,
+    audit_organization_id: str,
+    handling: str,
+    history: tuple[BackupHistoryRevisionSpec, ...],
+) -> None:
+    """Write fresh destination snapshots while preserving final quarantine."""
+    if await locked_history_revision(item_id) != 0:
+        raise RuntimeError("new backup item has an unexpected history revision")
+    first = history[0]
+    current = encrypt_value(first.value)
+    changed = await UserSecret.update_where(
+        {"id": field_id, "deleted_at__isnull": True},
+        value_encrypted=current,
+        value_hint=mask_value(first.value),
+        is_active=True,
+        updated_by=actor_id,
+        updated_at=datetime.now(UTC),
+    )
+    if changed.rows_affected != 1:
+        raise RuntimeError("backup password field disappeared during restore")
+    expected_revision = 0
+    started = datetime.now(UTC)
+    for revision in history:
+        after = current if revision.revision == 1 else encrypt_value(revision.value)
+        if revision.revision > 1:
+            changed = await UserSecret.update_where(
+                {"id": field_id, "deleted_at__isnull": True},
+                value_encrypted=after,
+                value_hint=mask_value(revision.value),
+                updated_by=actor_id,
+                updated_at=datetime.now(UTC),
+            )
+            if changed.rows_affected != 1:
+                raise RuntimeError("backup password field disappeared during restore")
+        snapshot = password_field_update_snapshot(
+            item_id=item_id,
+            item_user_id=actor_id,
+            audit_organization_id=audit_organization_id,
+            field_id=field_id,
+            field_key="password",
+            handling=handling,
+            execution_purpose="general",
+            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,
+            actor_id=actor_id,
+            audit_organization_id=audit_organization_id,
+            expected_revision=expected_revision,
+            snapshot=snapshot,
+        )
+        current = after
+    changed = await UserSecret.update_where(
+        {"id": field_id, "deleted_at__isnull": True},
+        is_active=False,
+        updated_by=actor_id,
+        updated_at=datetime.now(UTC),
+    )
+    if changed.rows_affected != 1:
+        raise RuntimeError("backup password field disappeared during restore")
+
+
 async def _validate_replay(item_id: str, actor_id: str) -> None:
     rows = (
         await CredentialItem.filter(id=item_id, deleted_at__isnull=True)

{matrx_orm-3.1.183 → matrx_orm-3.1.185}/matrx_orm/secrets_battery/items.py

@@ -1290,6 +1290,109 @@ async def add_credential_field(
     return _field_row(rows[0])
 
 
+def _captures_personal_password_history(
+    item_raw: dict[str, Any] | None,
+    field_raw: dict[str, Any],
+) -> bool:
+    """Return whether this locked row belongs in the private password history.
+
+    The module-local gate remains deliberately false in production. Keeping
+    eligibility here gives every existing-field ciphertext writer the same
+    future activation boundary without adding a caller-controlled switch.
+    """
+    return (
+        _PASSWORD_HISTORY_CAPTURE_ENABLED
+        and item_raw is not None
+        and item_raw.get("user_id") is not None
+        and item_raw.get("organization_id") is None
+        and field_raw.get("field_key") == "password"
+        and field_raw.get("handling") in {"visible", "revealable"}
+        and field_raw.get("execution_purpose") == GENERAL_EXECUTION_PURPOSE
+        and field_raw.get("is_active") is True
+    )
+
+
+async def _prepare_personal_password_history_capture(
+    *,
+    item_raw: dict[str, Any] | None,
+    field_raw: dict[str, Any],
+    actor_id: str | None,
+    audit_organization_id: str | None,
+) -> tuple[int, datetime] | None:
+    """Write the single allowed bootstrap before an eligible ciphertext change.
+
+    The caller already holds both the item and field locks. Returning the
+    locked next revision makes the later delta conditional on the same chain.
+    """
+    if not _captures_personal_password_history(item_raw, field_raw):
+        return None
+    if not actor_id or not audit_organization_id:
+        raise VaultHistorySnapshotError(
+            "personal password history requires actor and admitted audit organization"
+        )
+    assert item_raw is not None
+    item_id = str(item_raw["id"])
+    capture_started_at = datetime.now(UTC)
+    revision = await locked_history_revision(item_id)
+    if revision == 0:
+        encrypted = field_raw["value_encrypted"]
+        bootstrap = password_field_update_snapshot(
+            item_id=item_id,
+            item_user_id=str(item_raw["user_id"]),
+            audit_organization_id=audit_organization_id,
+            field_id=str(field_raw["id"]),
+            field_key=str(field_raw["field_key"]),
+            handling=str(field_raw["handling"]),
+            execution_purpose=str(field_raw["execution_purpose"]),
+            before_encrypted=encrypted,
+            after_encrypted=encrypted,
+            capture_started_at=capture_started_at,
+        )
+        revision = await write_password_field_update_snapshot(
+            item_id=item_id,
+            actor_id=actor_id,
+            audit_organization_id=audit_organization_id,
+            expected_revision=revision,
+            snapshot=bootstrap,
+        )
+    return revision, capture_started_at
+
+
+async def _append_personal_password_history_capture(
+    *,
+    capture: tuple[int, datetime] | None,
+    item_raw: dict[str, Any] | None,
+    field_raw: dict[str, Any],
+    after_encrypted: Any,
+    actor_id: str | None,
+    audit_organization_id: str | None,
+) -> None:
+    """Append the locked before-to-after delta after its ciphertext update."""
+    if capture is None:
+        return
+    assert item_raw is not None and actor_id and audit_organization_id
+    revision, capture_started_at = capture
+    snapshot = password_field_update_snapshot(
+        item_id=str(item_raw["id"]),
+        item_user_id=str(item_raw["user_id"]),
+        audit_organization_id=audit_organization_id,
+        field_id=str(field_raw["id"]),
+        field_key=str(field_raw["field_key"]),
+        handling=str(field_raw["handling"]),
+        execution_purpose=str(field_raw["execution_purpose"]),
+        before_encrypted=field_raw["value_encrypted"],
+        after_encrypted=after_encrypted,
+        capture_started_at=capture_started_at,
+    )
+    await write_password_field_update_snapshot(
+        item_id=str(item_raw["id"]),
+        actor_id=actor_id,
+        audit_organization_id=audit_organization_id,
+        expected_revision=revision,
+        snapshot=snapshot,
+    )
+
+
 async def update_credential_field_value(
     field_id: str,
     value: str,
@@ -1323,30 +1426,12 @@ async def update_credential_field_value(
                 f"field {raw.get('field_key') or raw.get('key')!r} is not editable — "
                 "it is managed by its owning integration"
             )
-        capture = (
-            _PASSWORD_HISTORY_CAPTURE_ENABLED and not system_rotation
-            and item_raw is not None and item_raw.get("user_id") is not None
-            and raw.get("field_key") == "password" and raw.get("handling") in {"visible", "revealable"}
-            and raw.get("execution_purpose") == GENERAL_EXECUTION_PURPOSE and raw.get("is_active") is True
+        capture = await _prepare_personal_password_history_capture(
+            item_raw=item_raw,
+            field_raw=raw,
+            actor_id=actor_id,
+            audit_organization_id=audit_organization_id,
         )
-        history_revision: int | None = None
-        capture_started_at = datetime.now(UTC)
-        if capture:
-            if not actor_id or not audit_organization_id:
-                raise VaultHistorySnapshotError("personal password history requires actor and admitted audit organization")
-            history_revision = await locked_history_revision(str(item_raw["id"]))
-            if history_revision == 0:
-                before = password_field_update_snapshot(
-                    item_id=str(item_raw["id"]), item_user_id=str(item_raw["user_id"]),
-                    audit_organization_id=audit_organization_id, field_id=field_id,
-                    field_key=str(raw["field_key"]), handling=str(raw["handling"]),
-                    execution_purpose=str(raw["execution_purpose"]), before_encrypted=raw["value_encrypted"],
-                    after_encrypted=raw["value_encrypted"], capture_started_at=capture_started_at,
-                )
-                history_revision = await write_password_field_update_snapshot(
-                    item_id=str(item_raw["id"]), actor_id=actor_id, audit_organization_id=audit_organization_id,
-                    expected_revision=history_revision, snapshot=before,
-                )
         encrypted_value = encrypt_value(value)
         await UserSecret.update_where(
             {"id": field_id, "deleted_at__isnull": True},
@@ -1355,19 +1440,14 @@ async def update_credential_field_value(
             updated_by=actor_id,
             updated_at=datetime.now(UTC),
         )
-        if capture:
-            assert item_raw is not None and history_revision is not None and actor_id and audit_organization_id
-            after = password_field_update_snapshot(
-                item_id=str(item_raw["id"]), item_user_id=str(item_raw["user_id"]),
-                audit_organization_id=audit_organization_id, field_id=field_id,
-                field_key=str(raw["field_key"]), handling=str(raw["handling"]),
-                execution_purpose=str(raw["execution_purpose"]), before_encrypted=raw["value_encrypted"],
-                after_encrypted=encrypted_value, capture_started_at=capture_started_at,
-            )
-            await write_password_field_update_snapshot(
-                item_id=str(item_raw["id"]), actor_id=actor_id, audit_organization_id=audit_organization_id,
-                expected_revision=history_revision, snapshot=after,
-            )
+        await _append_personal_password_history_capture(
+            capture=capture,
+            item_raw=item_raw,
+            field_raw=raw,
+            after_encrypted=encrypted_value,
+            actor_id=actor_id,
+            audit_organization_id=audit_organization_id,
+        )
     await record_secret_audit(
         action="rotated" if system_rotation else "field_updated",
         actor_id=actor_id,
@@ -1408,22 +1488,43 @@ async def rotate_credential_fields(
         item_raw = await _lock_item_raw(item_id)
         rows = await UserSecret.filter(
             credential_item_id=item_id, field_key__in=list(new_values), deleted_at__isnull=True
-        ).values("id", "field_key", "credential_item_id", "execution_purpose")
+        ).select_for_update().values(
+            "id", "field_key", "credential_item_id", "execution_purpose", "handling", "is_active", "value_encrypted"
+        )
         protected = [row for row in rows if _is_protected(row)]
         if protected:
             _refuse_protected(protected[0])
-        found = {str(r["field_key"]): str(r["id"]) for r in rows}
+        found = {str(r["field_key"]): r for r in rows}
         missing = sorted(set(new_values) - set(found))
         if missing:
             raise SecretNotFoundError(f"item {item_id} has no fields {missing} to rotate")
+        captures = {
+            fk: await _prepare_personal_password_history_capture(
+                item_raw=item_raw,
+                field_raw=field_raw,
+                actor_id=actor_id,
+                audit_organization_id=audit_organization_id,
+            )
+            for fk, field_raw in found.items()
+        }
         for fk, plaintext in new_values.items():
+            field_raw = found[fk]
+            encrypted_value = encrypt_value(plaintext)
             await UserSecret.update_where(
-                {"id": found[fk]},
-                value_encrypted=encrypt_value(plaintext),
+                {"id": str(field_raw["id"])},
+                value_encrypted=encrypted_value,
                 value_hint=mask_value(plaintext),
                 updated_by=actor_id,
                 updated_at=now,
             )
+            await _append_personal_password_history_capture(
+                capture=captures[fk],
+                item_raw=item_raw,
+                field_raw=field_raw,
+                after_encrypted=encrypted_value,
+                actor_id=actor_id,
+                audit_organization_id=audit_organization_id,
+            )
         await record_secret_audit(
             action="rotated",
             actor_id=actor_id,

{matrx_orm-3.1.183 → 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.183 → matrx_orm-3.1.185}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.183"
+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" }
@@ -41,7 +41,7 @@ dependencies = [
     "gitpython>=3.1.40",
     "psycopg[binary]>=3.2.5",
     "psycopg-pool>=3.2.5",
-    "matrx-utils>=2.0.54",
+    "matrx-utils>=2.0.55",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",

matrx_orm-3.1.185/tests/test_backup_history_restore.py

@@ -0,0 +1,144 @@
+"""Portable backup history is all-or-nothing before database insertion."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from datetime import UTC, datetime
+
+import pytest
+
+from matrx_orm.secrets_battery.backup_restore import (
+    BackupHistoryRevisionSpec,
+    _validate_history,
+)
+from matrx_orm.secrets_battery.items import FieldSpec
+
+
+def _password(value: str = "current") -> list[FieldSpec]:
+    return [FieldSpec(field_key="password", value=value, handling="revealable")]
+
+
+def _revision(number: int, value: str) -> BackupHistoryRevisionSpec:
+    return BackupHistoryRevisionSpec(number, value)
+
+
+def test_history_requires_complete_chain_ending_at_current_password():
+    result = _validate_history(
+        [_revision(1, "old"), _revision(2, "current")],
+        _password(),
+    )
+    assert [entry.revision for entry in result] == [1, 2]
+
+
+def test_history_allows_a_same_plaintext_delta_when_the_source_ciphertext_rotated():
+    result = _validate_history(
+        [_revision(1, "current"), _revision(2, "current")], _password()
+    )
+    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"),
+    [
+        ([_revision(2, "current")], _password()),
+        ([_revision(1, "old")], _password("current")),
+        ([_revision(1, "current")], []),
+        ([_revision(1, "current")], [FieldSpec(field_key="password", value="current", handling="sealed")]),
+    ],
+)
+def test_history_refuses_gap_sealed_or_current_value_mismatch_before_insert(history, fields):
+    with pytest.raises(ValueError):
+        _validate_history(history, fields)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("fields", "history"),
+    [
+        (_password(), [_revision(2, "current")]),
+        (
+            _password() + [FieldSpec(field_key="passkey_private", value="protected")],
+            [_revision(1, "current")],
+        ),
+    ],
+)
+async def test_invalid_history_or_protected_field_refuses_before_opening_restore_transaction(
+    monkeypatch, fields, history
+):
+    from matrx_orm.secrets_battery import backup_restore
+
+    opened = False
+
+    def forbidden_transaction(*_args, **_kwargs):
+        nonlocal opened
+        opened = True
+        raise AssertionError("history validation must precede database insertion")
+
+    monkeypatch.setattr(backup_restore, "transaction", forbidden_transaction)
+    with pytest.raises(ValueError, match="Invalid backup restore record"):
+        await backup_restore.create_backup_record_quarantined(
+            actor_id="11111111-1111-4111-8111-111111111111",
+            audit_organization_id="22222222-2222-4222-8222-222222222222",
+            mutation_id="33333333-3333-4333-8333-333333333333",
+            request_fingerprint=b"x" * 32,
+            display_name="test",
+            definition_key="website_login",
+            definition_version=1,
+            provider_key=None,
+            description=None,
+            tags=[],
+            login_urls=[],
+            uri_match_mode=None,
+            notes=None,
+            non_secret_fields=[],
+            fields=fields,
+            attachments=[],
+            history=history,
+        )
+    assert opened is False
+
+
+@pytest.mark.asyncio
+async def test_same_plaintext_delta_is_written_with_fresh_destination_ciphertext(monkeypatch):
+    from matrx_orm.secrets_battery import backup_restore, crypto
+
+    snapshots = []
+
+    async def revision(_item_id):
+        return 0
+
+    async def update(*_args, **_kwargs):
+        return SimpleNamespace(rows_affected=1)
+
+    async def write(**kwargs):
+        snapshots.append(kwargs["snapshot"])
+        return kwargs["expected_revision"] + 1
+
+    monkeypatch.setenv("CREDENTIALS_ENCRYPTION_KEY", "backup-history-test-key")
+    crypto.reset_encryption_for_tests()
+    monkeypatch.setattr(backup_restore, "locked_history_revision", revision)
+    monkeypatch.setattr(backup_restore.UserSecret, "update_where", update)
+    monkeypatch.setattr(backup_restore, "write_password_field_update_snapshot", write)
+    await backup_restore._write_quarantined_history(
+        item_id="11111111-1111-4111-8111-111111111111",
+        field_id="22222222-2222-4222-8222-222222222222",
+        actor_id="33333333-3333-4333-8333-333333333333",
+        audit_organization_id="44444444-4444-4444-8444-444444444444",
+        handling="revealable",
+        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"
+    ]