matrx-orm 3.1.166__tar.gz → 3.1.168__tar.gz

{matrx_orm-3.1.166 → matrx_orm-3.1.168}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.166
+Version: 3.1.168
 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
@@ -23,6 +23,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
 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.50

{matrx_orm-3.1.166 → matrx_orm-3.1.168}/matrx_orm/operations/create.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import asyncio
 from typing import Any, TYPE_CHECKING, Union
 
 from matrx_orm.state import StateManager
@@ -20,6 +21,19 @@ if TYPE_CHECKING:
 OnConflictArg = Union[list[str], "ConflictTarget"]
 
 
+def _prepare_instance_data(model_cls: type[Model], instance: Model) -> dict[str, Any]:
+    """Coerce a single insert row without occupying the request event loop."""
+    data: dict[str, Any] = {}
+    for field_name, field in model_cls._fields.items():
+        if isinstance(field, Field):
+            value = getattr(instance, field_name)
+            if value is None and field.default is not None:
+                value = field.get_default()
+            if value is not None:
+                data[field_name] = field.get_db_prep_value(value)
+    return data
+
+
 def _normalise_on_conflict(on_conflict: OnConflictArg) -> tuple[list[str], ConflictTarget | None]:
     """Internal: unify the two acceptable shapes.
 
@@ -85,14 +99,10 @@ async def save(instance: Model, *, statement_timeout: float | None = None) -> Mo
     model_cls = instance.__class__
     await pre_create.send(model_cls, instance=instance)
 
-    data: dict[str, Any] = {}
-    for field_name, field in model_cls._fields.items():
-        if isinstance(field, Field):
-            value = getattr(instance, field_name)
-            if value is None and field.default is not None:
-                value = field.get_default()
-            if value is not None:
-                data[field_name] = field.get_db_prep_value(value)
+    # JSONB conversion can recursively walk a large OCR/PDF payload and take
+    # seconds.  This is a shared write boundary, so every single-row create
+    # gets the same event-loop protection as the existing bulk write paths.
+    data = await asyncio.to_thread(_prepare_instance_data, model_cls, instance)
 
     query = QueryBuilder(model_cls)._build_query()
     query["data"] = data

{matrx_orm-3.1.166 → matrx_orm-3.1.168}/matrx_orm/secrets_battery/FEATURE.md

@@ -57,6 +57,8 @@ fork, and transfer refuse a protected child. Every competing child/lifecycle
 mutation locks and re-reads the parent in its transaction; whole-item delete
 remains atomic.
 
+**Native source admission (`native_source.py`).** `validate_native_source` is the server reader of the provider's exact source-v1 byte format; Rust remains the encoder and authenticator. It requires an explicit positive source-size limit, preserves nullable names and bytes, rejects duplicate/noncanonical JSON and COSE, and derives public metadata only after maintained P-256 key-pair validation. The result is provider-custody data, never a response model or generic field. `repr` and fixed failures omit material. `scripts/check_native_source_parity.py --rust-core <native-vault-provider/core>` compares the real compiled Rust reader against the server corpus; no mocked oracle. This prerequisite adds no creator, materializer, database row or native readiness. Verified September19 against132 focused tests and525 cross-language cases.
+
 **`inject_into_sandbox=true` REQUIRES an env alias — refused otherwise.** A
 container environment is a NAME→value map, so a field with `key IS NULL` has
 nowhere to land and bulk resolution drops it. Accepting the flag anyway meant a
@@ -94,7 +96,33 @@ refuses sealed bytes; `resolve_credential_attachment` is the trusted in-process
 path. Parent delete soft-deletes attachments atomically; fork decrypts and
 re-encrypts independent child rows; transfer needs no child rewrite because
 the parent is the sole ownership authority. Browser-facing list shapes never
-contain ciphertext or plaintext.
+contain ciphertext or plaintext. List serialization is deliberately outside
+the mutation and byte-materialization locking boundary.
+
+**Attachment serialization.** Every attachment mutation and byte materialization
+first identifies its parent, then in one `transaction(PACKAGE_DB_NAME)` locks and
+re-reads the live parent before it locks and re-reads the live child. The write
+or byte materialization and any audit use that same transaction. Propagated
+admission or operation errors roll the mutation back; database audit-storage
+errors retain `record_secret_audit`'s existing best-effort savepoint behavior.
+This is the
+same parent-first order as item delete, so delete wins cleanly over an add,
+metadata patch, replacement, child delete, human download, or trusted resolve;
+no child can be created, changed, or materialized under a deleted parent. The
+parent-delete helper deliberately takes no second parent lock because its caller
+already owns it; fork still locks its source parent and copies only its stable
+snapshot.
+
+**Live race recipe (requires an explicitly authorized disposable admin item).**
+Through the real Vault router and auth provider, create an admin-owned item and
+pause the attachment request after it takes its parent lock but before its child
+write. Releasing it first must return 201; the following item delete returns
+204 and a fresh router list has no live child. In the inverse ordering, complete
+the delete first and then release the attachment request: it must be refused
+and must not leave a live child. Repeat with download and trusted resolve paused
+before byte materialization. Remove the disposable item through the canonical
+cascade after each run. This is a live concurrency probe, never a replacement
+for the focused unit guards.
 
 **Grants: use the single-grant operations.** `add_item_grant` /
 `update_item_grant` / `remove_item_grant` change ONE recipient and leave the
@@ -328,6 +356,8 @@ delete).
 
 ## Change Log
 
+- **2026-09-19** — Added bounded source-v1 server admission reader with cbor2/cryptography and actual Rust differential parity; protected storage and native ceremonies remain separate pending units.
+
 - **2026-09-17 (3.1.160)** — **An audit row NAMES its organization, or nothing is
   written.** `record_secret_audit(organization_id=...)` is REQUIRED and refuses an
   empty value by name; it used to default to `None` "for legacy callers", and 51 of

{matrx_orm-3.1.166 → matrx_orm-3.1.168}/matrx_orm/secrets_battery/attachments.py

@@ -12,9 +12,11 @@ from dataclasses import dataclass
 from datetime import UTC, datetime
 from typing import Any
 
+from matrx_orm import transaction
+
 from .crypto import decrypt_bytes, encrypt_bytes
-from .items import CredentialItemNotFoundError, HANDLING_MODES, SealedFieldError
-from .model import CredentialAttachment, CredentialItem
+from .items import CredentialItemNotFoundError, HANDLING_MODES, SealedFieldError, _lock_item_raw
+from .model import PACKAGE_DB_NAME, CredentialAttachment, CredentialItem
 from .org_service import audit_organization, record_secret_audit
 from .service import SecretDecryptError
 
@@ -111,6 +113,20 @@ async def _require_raw(attachment_id: str) -> dict[str, Any]:
     return rows[0]
 
 
+async def _lock_attachment_raw(
+    attachment_id: str, *, parent_item_id: str
+) -> dict[str, Any]:
+    """Lock and re-read a live child after its parent is locked."""
+    rows = await (
+        CredentialAttachment.filter(id=attachment_id, deleted_at__isnull=True)
+        .select_for_update()
+        .values(*_ATTACHMENT_FIELDS, "value_encrypted")
+    )
+    if not rows or str(rows[0]["credential_item_id"]) != parent_item_id:
+        raise LookupError(f"credential attachment {attachment_id} not found")
+    return rows[0]
+
+
 def _validate_text(value: str, *, name: str, maximum: int) -> str:
     if not isinstance(value, str) or not value.strip():
         raise ValueError(f"{name} is required")
@@ -177,8 +193,6 @@ async def add_credential_attachment(
     audit_organization_id: str | None = None,
 ) -> CredentialAttachmentRow:
     """Encrypt and attach one file to an existing credential item."""
-    await _require_item(item_id)
-    parent_org = await _parent_item_organization(item_id)
     _validate_content(content)
     _validate_handling(handling)
     clean_label = _validate_text(label, name="label", maximum=200)
@@ -188,37 +202,44 @@ async def add_credential_attachment(
         if description and description.strip()
         else None
     )
-    instance = await CredentialAttachment.create(
-        credential_item_id=item_id,
-        label=clean_label,
-        description=clean_description,
-        file_name=clean_name,
-        media_type=_media_type(media_type),
-        size_bytes=len(content),
-        value_encrypted=encrypt_bytes(content),
-        handling=handling,
-        created_by=actor_id,
-        updated_by=actor_id,
-    )
-    await record_secret_audit(
-        action="attachment_added",
-        actor_id=actor_id,
-        organization_id=audit_organization(
-            record_organization_id=parent_org,
-            request_organization_id=audit_organization_id,
-            what=f"add_credential_attachment(item_id={item_id})",
-        ),
-        metadata={
-            "credential_item_id": item_id,
-            "attachment_id": str(instance.id),
-            "file_name": clean_name,
-            "size_bytes": len(content),
-            "handling": handling,
-        },
-    )
-    row = await get_credential_attachment(str(instance.id))
+    encrypted_content = encrypt_bytes(content)
+    instance_id: str | None = None
+    async with transaction(PACKAGE_DB_NAME):
+        parent = await _lock_item_raw(item_id)
+        instance = await CredentialAttachment.create(
+            credential_item_id=item_id,
+            label=clean_label,
+            description=clean_description,
+            file_name=clean_name,
+            media_type=_media_type(media_type),
+            size_bytes=len(content),
+            value_encrypted=encrypted_content,
+            handling=handling,
+            created_by=actor_id,
+            updated_by=actor_id,
+        )
+        instance_id = str(instance.id)
+        await record_secret_audit(
+            action="attachment_added",
+            actor_id=actor_id,
+            organization_id=audit_organization(
+                record_organization_id=parent.get("organization_id"),
+                request_organization_id=audit_organization_id,
+                what=f"add_credential_attachment(item_id={item_id})",
+            ),
+            metadata={
+                "credential_item_id": item_id,
+                "attachment_id": instance_id,
+                "file_name": clean_name,
+                "size_bytes": len(content),
+                "handling": handling,
+            },
+        )
+    if instance_id is None:
+        raise RuntimeError("credential attachment create completed without an id")
+    row = await get_credential_attachment(instance_id)
     if row is None:
-        raise RuntimeError(f"credential attachment {instance.id} vanished after create")
+        raise RuntimeError(f"credential attachment {instance_id} vanished after create")
     return row
 
 
@@ -236,14 +257,8 @@ async def update_credential_attachment_metadata(
     audit_organization_id: str | None = None,
 ) -> CredentialAttachmentRow:
     """Patch safe metadata without touching bytes or ``value_version``."""
-    raw = await _require_raw(attachment_id)
-    parent_org = await _parent_item_organization(str(raw["credential_item_id"]))
-    if handling is not None:
-        _validate_handling(handling)
-        if str(raw["handling"]) == "sealed" and handling != "sealed":
-            raise SealedFieldError(
-                f"attachment {raw['file_name']!r} is sealed — sealing is a one-way door"
-            )
+    initial = await _require_raw(attachment_id)
+    parent_item_id = str(initial["credential_item_id"])
     updates: dict[str, Any] = {"updated_by": actor_id, "updated_at": datetime.now(UTC)}
     if label is not None:
         updates["label"] = _validate_text(label, name="label", maximum=200)
@@ -260,21 +275,32 @@ async def update_credential_attachment_metadata(
     changed = sorted(set(updates) - {"updated_by", "updated_at"})
     if not changed:
         raise ValueError("no attachment metadata changes supplied")
-    await CredentialAttachment.update_where({"id": attachment_id}, **updates)
-    await record_secret_audit(
-        action="attachment_updated",
-        actor_id=actor_id,
-        organization_id=audit_organization(
-            record_organization_id=parent_org,
-            request_organization_id=audit_organization_id,
-            what=f"update_credential_attachment_metadata(attachment_id={attachment_id})",
-        ),
-        metadata={
-            "credential_item_id": str(raw["credential_item_id"]),
-            "attachment_id": attachment_id,
-            "changed": changed,
-        },
-    )
+    if handling is not None:
+        _validate_handling(handling)
+    async with transaction(PACKAGE_DB_NAME):
+        parent = await _lock_item_raw(parent_item_id)
+        raw = await _lock_attachment_raw(attachment_id, parent_item_id=parent_item_id)
+        if handling is not None and str(raw["handling"]) == "sealed" and handling != "sealed":
+            raise SealedFieldError(
+                f"attachment {raw['file_name']!r} is sealed — sealing is a one-way door"
+            )
+        await CredentialAttachment.update_where(
+            {"id": attachment_id, "deleted_at__isnull": True}, **updates
+        )
+        await record_secret_audit(
+            action="attachment_updated",
+            actor_id=actor_id,
+            organization_id=audit_organization(
+                record_organization_id=parent.get("organization_id"),
+                request_organization_id=audit_organization_id,
+                what=f"update_credential_attachment_metadata(attachment_id={attachment_id})",
+            ),
+            metadata={
+                "credential_item_id": parent_item_id,
+                "attachment_id": attachment_id,
+                "changed": changed,
+            },
+        )
     row = await get_credential_attachment(attachment_id)
     if row is None:
         raise LookupError(f"credential attachment {attachment_id} not found")
@@ -291,34 +317,38 @@ async def replace_credential_attachment(
     audit_organization_id: str | None = None,
 ) -> CredentialAttachmentRow:
     """Atomically replace the encrypted bytes and file metadata."""
-    raw = await _require_raw(attachment_id)
-    parent_org = await _parent_item_organization(str(raw["credential_item_id"]))
+    initial = await _require_raw(attachment_id)
+    parent_item_id = str(initial["credential_item_id"])
     _validate_content(content)
     clean_name = _validate_text(file_name, name="file_name", maximum=512)
-    await CredentialAttachment.update_where(
-        {"id": attachment_id, "deleted_at__isnull": True},
-        file_name=clean_name,
-        media_type=_media_type(media_type),
-        size_bytes=len(content),
-        value_encrypted=encrypt_bytes(content),
-        updated_by=actor_id,
-        updated_at=datetime.now(UTC),
-    )
-    await record_secret_audit(
-        action="attachment_replaced",
-        actor_id=actor_id,
-        organization_id=audit_organization(
-            record_organization_id=parent_org,
-            request_organization_id=audit_organization_id,
-            what=f"replace_credential_attachment(attachment_id={attachment_id})",
-        ),
-        metadata={
-            "credential_item_id": str(raw["credential_item_id"]),
-            "attachment_id": attachment_id,
-            "file_name": clean_name,
-            "size_bytes": len(content),
-        },
-    )
+    encrypted_content = encrypt_bytes(content)
+    async with transaction(PACKAGE_DB_NAME):
+        parent = await _lock_item_raw(parent_item_id)
+        await _lock_attachment_raw(attachment_id, parent_item_id=parent_item_id)
+        await CredentialAttachment.update_where(
+            {"id": attachment_id, "deleted_at__isnull": True},
+            file_name=clean_name,
+            media_type=_media_type(media_type),
+            size_bytes=len(content),
+            value_encrypted=encrypted_content,
+            updated_by=actor_id,
+            updated_at=datetime.now(UTC),
+        )
+        await record_secret_audit(
+            action="attachment_replaced",
+            actor_id=actor_id,
+            organization_id=audit_organization(
+                record_organization_id=parent.get("organization_id"),
+                request_organization_id=audit_organization_id,
+                what=f"replace_credential_attachment(attachment_id={attachment_id})",
+            ),
+            metadata={
+                "credential_item_id": parent_item_id,
+                "attachment_id": attachment_id,
+                "file_name": clean_name,
+                "size_bytes": len(content),
+            },
+        )
     row = await get_credential_attachment(attachment_id)
     if row is None:
         raise LookupError(f"credential attachment {attachment_id} not found")
@@ -331,31 +361,36 @@ async def delete_credential_attachment(
     actor_id: str | None = None,
     audit_organization_id: str | None = None,
 ) -> bool:
-    raw = await _require_raw(attachment_id)
-    parent_org = await _parent_item_organization(str(raw["credential_item_id"]))
+    initial = await _require_raw(attachment_id)
+    parent_item_id = str(initial["credential_item_id"])
     now = datetime.now(UTC)
-    result = await CredentialAttachment.update_where(
-        {"id": attachment_id, "deleted_at__isnull": True},
-        deleted_at=now,
-        updated_by=actor_id,
-        updated_at=now,
-    )
-    if result.rows_affected:
-        await record_secret_audit(
-            action="attachment_deleted",
-            actor_id=actor_id,
-            organization_id=audit_organization(
-                record_organization_id=parent_org,
-                request_organization_id=audit_organization_id,
-                what=f"delete_credential_attachment(attachment_id={attachment_id})",
-            ),
-            metadata={
-                "credential_item_id": str(raw["credential_item_id"]),
-                "attachment_id": attachment_id,
-                "file_name": str(raw["file_name"]),
-            },
+    deleted = False
+    async with transaction(PACKAGE_DB_NAME):
+        parent = await _lock_item_raw(parent_item_id)
+        raw = await _lock_attachment_raw(attachment_id, parent_item_id=parent_item_id)
+        result = await CredentialAttachment.update_where(
+            {"id": attachment_id, "deleted_at__isnull": True},
+            deleted_at=now,
+            updated_by=actor_id,
+            updated_at=now,
         )
-    return result.rows_affected > 0
+        if result.rows_affected:
+            deleted = True
+            await record_secret_audit(
+                action="attachment_deleted",
+                actor_id=actor_id,
+                organization_id=audit_organization(
+                    record_organization_id=parent.get("organization_id"),
+                    request_organization_id=audit_organization_id,
+                    what=f"delete_credential_attachment(attachment_id={attachment_id})",
+                ),
+                metadata={
+                    "credential_item_id": parent_item_id,
+                    "attachment_id": attachment_id,
+                    "file_name": str(raw["file_name"]),
+                },
+            )
+    return deleted
 
 
 async def reveal_credential_attachment(
@@ -365,64 +400,83 @@ async def reveal_credential_attachment(
     audit_organization_id: str | None = None,
 ) -> tuple[CredentialAttachmentRow, bytes]:
     """Human download path. Sealed bytes are structurally refused."""
-    raw = await _require_raw(attachment_id)
-    parent_org = await _parent_item_organization(str(raw["credential_item_id"]))
-    if str(raw["handling"]) == "sealed":
-        await record_secret_audit(
-            action="attachment_download_denied",
-            actor_id=actor_id,
-            organization_id=audit_organization(
-                record_organization_id=parent_org,
-                request_organization_id=audit_organization_id,
-                what=f"reveal_credential_attachment(attachment_id={attachment_id})",
-            ),
-            metadata={
-                "credential_item_id": str(raw["credential_item_id"]),
-                "attachment_id": attachment_id,
-                "reason": "sealed",
-            },
-        )
-        raise SealedFieldError(
-            f"attachment {raw['file_name']!r} is sealed — no human-facing API may return it"
-        )
-    try:
-        content = decrypt_bytes(raw["value_encrypted"])
-    except Exception as exc:
-        raise SecretDecryptError(
-            f"credential attachment {attachment_id} does not decrypt with the configured key"
-        ) from exc
-    await CredentialAttachment.update_where({"id": attachment_id}, last_used_at=datetime.now(UTC))
-    await record_secret_audit(
-        action="attachment_downloaded",
-        actor_id=actor_id,
-        organization_id=audit_organization(
-            record_organization_id=parent_org,
-            request_organization_id=audit_organization_id,
-            what=f"reveal_credential_attachment(attachment_id={attachment_id})",
-        ),
-        metadata={
-            "credential_item_id": str(raw["credential_item_id"]),
-            "attachment_id": attachment_id,
-            "file_name": str(raw["file_name"]),
-            "size_bytes": int(raw["size_bytes"]),
-        },
-    )
-    return _row(raw), content
+    initial = await _require_raw(attachment_id)
+    parent_item_id = str(initial["credential_item_id"])
+    denied_error: SealedFieldError | None = None
+    result: tuple[CredentialAttachmentRow, bytes] | None = None
+    async with transaction(PACKAGE_DB_NAME):
+        parent = await _lock_item_raw(parent_item_id)
+        raw = await _lock_attachment_raw(attachment_id, parent_item_id=parent_item_id)
+        if str(raw["handling"]) == "sealed":
+            await record_secret_audit(
+                action="attachment_download_denied",
+                actor_id=actor_id,
+                organization_id=audit_organization(
+                    record_organization_id=parent.get("organization_id"),
+                    request_organization_id=audit_organization_id,
+                    what=f"reveal_credential_attachment(attachment_id={attachment_id})",
+                ),
+                metadata={
+                    "credential_item_id": parent_item_id,
+                    "attachment_id": attachment_id,
+                    "reason": "sealed",
+                },
+            )
+            denied_error = SealedFieldError(
+                f"attachment {raw['file_name']!r} is sealed — no human-facing API may return it"
+            )
+        else:
+            try:
+                content = decrypt_bytes(raw["value_encrypted"])
+            except Exception as exc:
+                raise SecretDecryptError(
+                    f"credential attachment {attachment_id} does not decrypt with the configured key"
+                ) from exc
+            await CredentialAttachment.update_where(
+                {"id": attachment_id, "deleted_at__isnull": True}, last_used_at=datetime.now(UTC)
+            )
+            await record_secret_audit(
+                action="attachment_downloaded",
+                actor_id=actor_id,
+                organization_id=audit_organization(
+                    record_organization_id=parent.get("organization_id"),
+                    request_organization_id=audit_organization_id,
+                    what=f"reveal_credential_attachment(attachment_id={attachment_id})",
+                ),
+                metadata={
+                    "credential_item_id": parent_item_id,
+                    "attachment_id": attachment_id,
+                    "file_name": str(raw["file_name"]),
+                    "size_bytes": int(raw["size_bytes"]),
+                },
+            )
+            result = (_row(raw), content)
+    if denied_error is not None:
+        raise denied_error
+    if result is None:
+        raise RuntimeError("attachment download completed without a result")
+    return result
 
 
 async def resolve_credential_attachment(
     attachment_id: str,
 ) -> tuple[CredentialAttachmentRow, bytes]:
     """Trusted execution path, including sealed attachments."""
-    raw = await _require_raw(attachment_id)
-    try:
-        content = decrypt_bytes(raw["value_encrypted"])
-    except Exception as exc:
-        raise SecretDecryptError(
-            f"credential attachment {attachment_id} does not decrypt with the configured key"
-        ) from exc
-    await CredentialAttachment.update_where({"id": attachment_id}, last_used_at=datetime.now(UTC))
-    return _row(raw), content
+    initial = await _require_raw(attachment_id)
+    parent_item_id = str(initial["credential_item_id"])
+    async with transaction(PACKAGE_DB_NAME):
+        await _lock_item_raw(parent_item_id)
+        raw = await _lock_attachment_raw(attachment_id, parent_item_id=parent_item_id)
+        try:
+            content = decrypt_bytes(raw["value_encrypted"])
+        except Exception as exc:
+            raise SecretDecryptError(
+                f"credential attachment {attachment_id} does not decrypt with the configured key"
+            ) from exc
+        await CredentialAttachment.update_where(
+            {"id": attachment_id, "deleted_at__isnull": True}, last_used_at=datetime.now(UTC)
+        )
+        return _row(raw), content
 
 
 async def soft_delete_item_attachments(item_id: str, *, actor_id: str | None = None) -> int: