matrx-orm 3.1.140__tar.gz → 3.1.141__tar.gz

{matrx_orm-3.1.140 → matrx_orm-3.1.141}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.140
+Version: 3.1.141
 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
@@ -25,7 +25,7 @@ Requires-Python: >=3.13
 Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: cryptography>=43.0
 Requires-Dist: gitpython>=3.1.40
-Requires-Dist: matrx-utils>=2.0.36
+Requires-Dist: matrx-utils>=2.0.38
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

{matrx_orm-3.1.140 → matrx_orm-3.1.141}/matrx_orm/secrets_battery/FEATURE.md

@@ -47,6 +47,16 @@ artifacts, not general document storage.
 `editable=false` blocks human value changes (`FieldNotEditableError`); the owning
 service rotates via `system_rotation=True` / `rotate_credential_fields`.
 
+**Protected execution purpose.** `execution_purpose` is a closed, immutable
+row purpose. `passkey_private` is reserved for native-provider use and is
+never creatable through generic battery or HTTP constructors. Generic
+single-field resolution refuses it before decrypt with the stable
+`protected_execution_required` code; bulk env/token resolution omits it.
+Item metadata and grants remain metadata-only, while generic child mutation,
+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.
+
 **`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

{matrx_orm-3.1.140 → matrx_orm-3.1.141}/matrx_orm/secrets_battery/__init__.py

@@ -76,6 +76,7 @@ from .items import (
     CredentialItemNotFoundError,
     CredentialItemRow,
     FieldNotEditableError,
+    ProtectedSecretPurposeError,
     FieldSpec,
     ItemGrantSpec,
     SandboxInjectionWithoutEnvKeyError,
@@ -210,6 +211,7 @@ __all__ = [
     "CredentialItemNotFoundError",
     "CredentialItemRow",
     "FieldNotEditableError",
+    "ProtectedSecretPurposeError",
     "FieldSpec",
     "ItemGrantSpec",
     "SandboxInjectionWithoutEnvKeyError",

{matrx_orm-3.1.140 → matrx_orm-3.1.141}/matrx_orm/secrets_battery/items.py

@@ -67,6 +67,9 @@ def register_non_transferable_field_key(field_key: str) -> None:
 
 
 HANDLING_MODES: tuple[str, ...] = ("visible", "revealable", "sealed")
+GENERAL_EXECUTION_PURPOSE = "general"
+PASSKEY_PRIVATE_EXECUTION_PURPOSE = "passkey_private"
+PROTECTED_FIELD_KEY = "passkey_private"
 ITEM_STATUSES: tuple[str, ...] = ("active", "disabled", "expired", "pending_verification")
 URI_MATCH_MODES: tuple[str, ...] = ("host", "domain", "exact", "never")
 ITEM_SOURCES: tuple[str, ...] = (
@@ -107,6 +110,24 @@ class SandboxInjectionWithoutEnvKeyError(ValueError):
     together) or leave injection off."""
 
 
+class ProtectedSecretPurposeError(PermissionError):
+    """A generic path reached a native-provider-only secret before decrypt."""
+
+    code = "protected_execution_required"
+
+    def __init__(self, *, field_id: str | None, credential_item_id: str | None) -> None:
+        self.field_id = field_id
+        self.credential_item_id = credential_item_id
+        super().__init__(self.code)
+
+    def metadata(self) -> dict[str, str | None]:
+        return {
+            "code": self.code,
+            "field_id": self.field_id,
+            "credential_item_id": self.credential_item_id,
+        }
+
+
 # ── Shapes ────────────────────────────────────────────────────────────────
 
 
@@ -153,6 +174,7 @@ class CredentialFieldRow:
     description: str | None
     created_at: str
     updated_at: str
+    execution_purpose: str
 
     def to_dict(self) -> dict[str, Any]:
         return dict(self.__dict__)
@@ -308,6 +330,7 @@ _FIELD_FIELDS = (
     "id",
     "credential_item_id",
     "field_key",
+    "execution_purpose",
     "key",
     "handling",
     "editable",
@@ -354,6 +377,7 @@ def _field_row(raw: dict[str, Any]) -> CredentialFieldRow:
         id=str(raw["id"]),
         credential_item_id=str(raw["credential_item_id"]),
         field_key=str(raw["field_key"] or ""),
+        execution_purpose=_execution_purpose(raw),
         env_key=raw.get("key"),
         handling=str(raw.get("handling") or "revealable"),
         editable=bool(raw.get("editable", True)),
@@ -388,6 +412,47 @@ async def _require_item_raw(item_id: str) -> dict[str, Any]:
     return rows[0]
 
 
+async def _lock_item_raw(item_id: str) -> dict[str, Any]:
+    """Lock and re-read a live parent within the current transaction."""
+    rows = await (
+        CredentialItem.filter(id=item_id, deleted_at__isnull=True)
+        .select_for_update()
+        .values(*_ITEM_FIELDS)
+    )
+    if not rows:
+        raise CredentialItemNotFoundError(f"credential item {item_id} not found")
+    return rows[0]
+
+
+def _execution_purpose(raw: dict[str, Any]) -> str:
+    purpose = raw.get("execution_purpose")
+    if purpose not in (GENERAL_EXECUTION_PURPOSE, PASSKEY_PRIVATE_EXECUTION_PURPOSE):
+        # A missing projection is a security-contract failure, never evidence
+        # that the row is ordinary.
+        raise ProtectedSecretPurposeError(
+            field_id=str(raw["id"]) if raw.get("id") else None,
+            credential_item_id=(str(raw["credential_item_id"]) if raw.get("credential_item_id") else None),
+        )
+    return str(purpose)
+
+
+def _is_protected(raw: dict[str, Any]) -> bool:
+    return _execution_purpose(raw) == PASSKEY_PRIVATE_EXECUTION_PURPOSE
+
+
+def _refuse_protected(raw: dict[str, Any]) -> None:
+    if _is_protected(raw):
+        raise ProtectedSecretPurposeError(
+            field_id=str(raw["id"]) if raw.get("id") else None,
+            credential_item_id=(str(raw["credential_item_id"]) if raw.get("credential_item_id") else None),
+        )
+
+
+def _refuse_reserved_generic_field(field_key: str) -> None:
+    if field_key == PROTECTED_FIELD_KEY:
+        raise ValueError("field_key 'passkey_private' is reserved for native provider execution")
+
+
 # ── Item CRUD ─────────────────────────────────────────────────────────────
 
 
@@ -516,6 +581,7 @@ async def create_credential_bundle(
     seen: set[str] = set()
     for spec in fields:
         _validate_field_key(spec.field_key)
+        _refuse_reserved_generic_field(spec.field_key)
         _validate_handling(spec.handling)
         _validate_sandbox_injectable(
             field_key=spec.field_key,
@@ -693,9 +759,9 @@ async def delete_credential_item(
 ) -> None:
     """Soft-delete the item, all its fields, and drop its grants — atomically.
     Resolution stops immediately; ciphertext is recoverable until purge."""
-    raw = await _require_item_raw(item_id)
     now = datetime.now(UTC)
     async with transaction(PACKAGE_DB_NAME):
+        raw = await _lock_item_raw(item_id)
         from .attachments import soft_delete_item_attachments
 
         await UserSecretGrant.delete_where(credential_item_id=item_id)
@@ -743,6 +809,7 @@ async def add_credential_field(
     first, then write.
     """
     _validate_field_key(spec.field_key)
+    _refuse_reserved_generic_field(spec.field_key)
     _validate_handling(spec.handling)
     if spec.handling == "sealed":
         await require_host_authorization(
@@ -758,30 +825,31 @@ async def add_credential_field(
     )
     if not isinstance(spec.value, str):
         raise ValueError("value must be a string")
-    raw = await _require_item_raw(item_id)
-    instance = await UserSecret.create(
-        user_id=raw.get("user_id"),
-        organization_id=raw.get("organization_id"),
-        credential_item_id=item_id,
-        field_key=spec.field_key,
-        key=spec.env_key,
-        value_encrypted=encrypt_value(spec.value),
-        value_hint=mask_value(spec.value),
-        handling=spec.handling,
-        editable=spec.editable,
-        inject_into_sandbox=spec.inject_into_sandbox,
-        description=spec.description,
-        access_mode=str(raw.get("access_mode") or "all_members"),
-        created_by=actor_id,
-        updated_by=actor_id,
-    )
-    await record_secret_audit(
-        action="field_added",
-        actor_id=actor_id,
-        user_secret_id=str(instance.id),
-        organization_id=audit_organization_id,
-        metadata={"credential_item_id": item_id, "field_key": spec.field_key},
-    )
+    async with transaction(PACKAGE_DB_NAME):
+        raw = await _lock_item_raw(item_id)
+        instance = await UserSecret.create(
+            user_id=raw.get("user_id"),
+            organization_id=raw.get("organization_id"),
+            credential_item_id=item_id,
+            field_key=spec.field_key,
+            key=spec.env_key,
+            value_encrypted=encrypt_value(spec.value),
+            value_hint=mask_value(spec.value),
+            handling=spec.handling,
+            editable=spec.editable,
+            inject_into_sandbox=spec.inject_into_sandbox,
+            description=spec.description,
+            access_mode=str(raw.get("access_mode") or "all_members"),
+            created_by=actor_id,
+            updated_by=actor_id,
+        )
+        await record_secret_audit(
+            action="field_added",
+            actor_id=actor_id,
+            user_secret_id=str(instance.id),
+            organization_id=audit_organization_id,
+            metadata={"credential_item_id": item_id, "field_key": spec.field_key},
+        )
     rows = await UserSecret.filter(id=instance.id).values(*_FIELD_FIELDS)
     return _field_row(rows[0])
 
@@ -800,22 +868,31 @@ async def update_credential_field_value(
     token refresh, key rotation)."""
     if not isinstance(value, str):
         raise ValueError("value must be a string")
-    rows = await UserSecret.filter(id=field_id, deleted_at__isnull=True).values(*_FIELD_FIELDS)
+    rows = await UserSecret.filter(id=field_id, deleted_at__isnull=True).values("credential_item_id")
     if not rows:
         raise SecretNotFoundError(f"credential field {field_id} not found")
-    raw = rows[0]
-    if not bool(raw.get("editable", True)) and not system_rotation:
-        raise FieldNotEditableError(
-            f"field {raw.get('field_key') or raw.get('key')!r} is not editable — "
-            "it is managed by its owning integration"
+    async with transaction(PACKAGE_DB_NAME):
+        if rows[0].get("credential_item_id"):
+            await _lock_item_raw(str(rows[0]["credential_item_id"]))
+        rows = await UserSecret.filter(id=field_id, deleted_at__isnull=True).select_for_update().values(
+            *_FIELD_FIELDS
+        )
+        if not rows:
+            raise SecretNotFoundError(f"credential field {field_id} not found")
+        raw = rows[0]
+        _refuse_protected(raw)
+        if not bool(raw.get("editable", True)) and not system_rotation:
+            raise FieldNotEditableError(
+                f"field {raw.get('field_key') or raw.get('key')!r} is not editable — "
+                "it is managed by its owning integration"
+            )
+        await UserSecret.update_where(
+            {"id": field_id, "deleted_at__isnull": True},
+            value_encrypted=encrypt_value(value),
+            value_hint=mask_value(value),
+            updated_by=actor_id,
+            updated_at=datetime.now(UTC),
         )
-    await UserSecret.update_where(
-        {"id": field_id, "deleted_at__isnull": True},
-        value_encrypted=encrypt_value(value),
-        value_hint=mask_value(value),
-        updated_by=actor_id,
-        updated_at=datetime.now(UTC),
-    )
     await record_secret_audit(
         action="rotated" if system_rotation else "field_updated",
         actor_id=actor_id,
@@ -852,10 +929,13 @@ async def rotate_credential_fields(
     async with transaction(PACKAGE_DB_NAME):
         # Item + field liveness re-checked INSIDE the transaction so a
         # concurrent delete can't race a half-rotation in.
-        await _require_item_raw(item_id)
+        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")
+        ).values("id", "field_key", "credential_item_id", "execution_purpose")
+        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}
         missing = sorted(set(new_values) - set(found))
         if missing:
@@ -916,12 +996,18 @@ async def update_field_metadata(
             raise ValueError(f"env_key must match {VALID_KEY_RE}; got {env_key!r}")
 
     async with transaction(PACKAGE_DB_NAME):
-        rows = await UserSecret.filter(id=field_id, deleted_at__isnull=True).values(
+        rows = await UserSecret.filter(id=field_id, deleted_at__isnull=True).values("credential_item_id")
+        if not rows:
+            raise SecretNotFoundError(f"credential field {field_id} not found")
+        if rows[0].get("credential_item_id"):
+            await _lock_item_raw(str(rows[0]["credential_item_id"]))
+        rows = await UserSecret.filter(id=field_id, deleted_at__isnull=True).select_for_update().values(
             *_FIELD_FIELDS, "user_id", "organization_id"
         )
         if not rows:
             raise SecretNotFoundError(f"credential field {field_id} not found")
         raw = rows[0]
+        _refuse_protected(raw)
 
         if handling is not None and str(raw.get("handling")) == "sealed" and handling != "sealed":
             raise SealedFieldError(
@@ -1000,13 +1086,26 @@ async def delete_credential_field(
     actor_id: str | None = None,
 ) -> bool:
     """Soft-delete one field. Returns True when a row was affected."""
-    result = await UserSecret.update_where(
-        {"id": field_id, "deleted_at__isnull": True},
-        deleted_at=datetime.now(UTC),
-        is_active=False,
-        updated_by=actor_id,
-        updated_at=datetime.now(UTC),
-    )
+    rows = await UserSecret.filter(id=field_id, deleted_at__isnull=True).values("credential_item_id")
+    if not rows:
+        return False
+    async with transaction(PACKAGE_DB_NAME):
+        if rows[0].get("credential_item_id"):
+            await _lock_item_raw(str(rows[0]["credential_item_id"]))
+        rows = await UserSecret.filter(id=field_id, deleted_at__isnull=True).select_for_update().values(
+            "id", "credential_item_id", "execution_purpose"
+        )
+        if not rows:
+            return False
+        raw = rows[0]
+        _refuse_protected(raw)
+        result = await UserSecret.update_where(
+            {"id": field_id, "deleted_at__isnull": True},
+            deleted_at=datetime.now(UTC),
+            is_active=False,
+            updated_by=actor_id,
+            updated_at=datetime.now(UTC),
+        )
     if result.rows_affected:
         await record_secret_audit(
             action="field_deleted",
@@ -1025,10 +1124,11 @@ async def resolve_field_by_id(field_id: str) -> str:
     ``sealed`` fields; never expose through a human-facing surface. The host
     must have authorized the consumer before calling."""
     rows = await UserSecret.filter(id=field_id, deleted_at__isnull=True, is_active=True).values(
-        "id", "field_key", "key", "value_encrypted"
+        "id", "credential_item_id", "field_key", "key", "execution_purpose", "value_encrypted"
     )
     if not rows:
         raise SecretNotFoundError(f"credential field {field_id} not found")
+    _refuse_protected(rows[0])
     try:
         value = decrypt_value(rows[0]["value_encrypted"])
     except Exception as exc:
@@ -1048,9 +1148,10 @@ async def resolve_field(item_id: str, field_key: str) -> str:
         field_key=field_key,
         deleted_at__isnull=True,
         is_active=True,
-    ).values("id")
+    ).values("id", "credential_item_id", "execution_purpose")
     if not rows:
         raise SecretNotFoundError(f"item {item_id} has no active field {field_key!r}")
+    _refuse_protected(rows[0])
     return await resolve_field_by_id(str(rows[0]["id"]))
 
 
@@ -1062,6 +1163,7 @@ async def resolve_item_fields(item_id: str, *, sandbox_only: bool = False) -> di
         "credential_item_id": item_id,
         "deleted_at__isnull": True,
         "is_active": True,
+        "execution_purpose": GENERAL_EXECUTION_PURPOSE,
     }
     if sandbox_only:
         filters["inject_into_sandbox"] = True
@@ -1103,14 +1205,19 @@ async def reveal_field(
             field_key=field_key,
             deleted_at__isnull=True,
             is_active=True,
-        ).values("id", "field_key", "key", "handling", "value_encrypted", "credential_item_id")
+        ).values(
+            "id", "field_key", "key", "handling", "execution_purpose", "value_encrypted",
+            "credential_item_id",
+        )
     else:
         rows = await UserSecret.filter(id=field_id, deleted_at__isnull=True, is_active=True).values(
-            "id", "field_key", "key", "handling", "value_encrypted", "credential_item_id"
+            "id", "field_key", "key", "handling", "execution_purpose", "value_encrypted",
+            "credential_item_id",
         )
     if not rows:
         raise SecretNotFoundError("credential field not found")
     raw = rows[0]
+    _refuse_protected(raw)
     handling = str(raw.get("handling") or "revealable")
     if handling == "sealed":
         await record_secret_audit(
@@ -1463,11 +1570,18 @@ async def transfer_credential_item(
     do NOT travel: they are retired in the same transaction and named in the
     returned :class:`TransferResult`."""
     _validate_owner(to_user_id, to_organization_id)
-    raw = await _require_item_raw(item_id)
-    from_user_id = str(raw["user_id"]) if raw.get("user_id") else None
-    from_organization_id = str(raw["organization_id"]) if raw.get("organization_id") else None
     now = datetime.now(UTC)
     async with transaction(PACKAGE_DB_NAME):
+        raw = await _lock_item_raw(item_id)
+        protected = await UserSecret.filter(
+            credential_item_id=item_id,
+            deleted_at__isnull=True,
+            execution_purpose=PASSKEY_PRIVATE_EXECUTION_PURPOSE,
+        ).values("id", "credential_item_id", "execution_purpose")
+        if protected:
+            _refuse_protected(protected[0])
+        from_user_id = str(raw["user_id"]) if raw.get("user_id") else None
+        from_organization_id = str(raw["organization_id"]) if raw.get("organization_id") else None
         retired = await _retire_non_transferable_fields(
             item_id, actor_id=actor_id, now=now, event="transfer"
         )
@@ -1534,29 +1648,22 @@ async def fork_credential_item(
     hands the copy to a principal who never established them (D-15). The new
     item's ``lifecycle.fields_not_copied`` names what was left behind."""
     _validate_owner(to_user_id, to_organization_id)
-    raw = await _require_item_raw(item_id)
-    all_field_rows = await UserSecret.filter(
-        credential_item_id=item_id, deleted_at__isnull=True
-    ).values(*_FIELD_FIELDS, "value_encrypted")
-    field_rows = [
-        fr for fr in all_field_rows if str(fr.get("field_key")) not in NON_TRANSFERABLE_FIELD_KEYS
-    ]
-    not_copied = sorted(
-        {
+    async with transaction(PACKAGE_DB_NAME):
+        raw = await _lock_item_raw(item_id)
+        all_field_rows = await UserSecret.filter(
+            credential_item_id=item_id, deleted_at__isnull=True
+        ).values(*_FIELD_FIELDS, "value_encrypted")
+        protected = [row for row in all_field_rows if _is_protected(row)]
+        if protected:
+            _refuse_protected(protected[0])
+        field_rows = [
+            fr for fr in all_field_rows if str(fr.get("field_key")) not in NON_TRANSFERABLE_FIELD_KEYS
+        ]
+        not_copied = sorted(
             str(fr.get("field_key"))
             for fr in all_field_rows
             if str(fr.get("field_key")) in NON_TRANSFERABLE_FIELD_KEYS
-        }
-    )
-    if not_copied:
-        logger.warning(
-            "credential item %s: fork does NOT copy minting field(s) %s — the fork's "
-            "owner must establish them again (D-15)",
-            item_id,
-            not_copied,
         )
-
-    async with transaction(PACKAGE_DB_NAME):
         new_item = await CredentialItem.create(
             user_id=to_user_id,
             organization_id=to_organization_id,

{matrx_orm-3.1.140 → matrx_orm-3.1.141}/matrx_orm/secrets_battery/model.py

@@ -80,6 +80,7 @@ class UserSecret(Model):
     source_user_secret_version = IntegerField()
     credential_item_id = UUIDField()
     field_key = TextField()
+    execution_purpose = TextField(null=False, default="general")
     handling = TextField(null=False, default="revealable")
     editable = BooleanField(null=False, default=True)
     key = TextField()