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

{matrx_orm-3.1.140 → matrx_orm-3.1.142}/CLAUDE.md

@@ -52,7 +52,7 @@ Every table that becomes a Model needs row identity: a single-column primary key
 - **Schema builder** (`matrx_orm.schema_builder`): code generation for Python + TypeScript type definitions from the DB schema. Postgres **VIEWs** are emitted as **read-only `Model` classes** into the same schema models file (on by default; per-entry `output.include_views: false` opts a schema out, `output.exclude_views: [...]` skips individual views). View models get no manager/DTO/base-class/auto_config (views are not writable), synthesize `_primary_keys` from an `id` column (else the first column, for cache-key/`load_by_id` only), and emit plain typed fields with **no `ForeignKey`** (views carry no FK metadata — nothing cross-schema to resolve). Never hand-write a view model again.
 - **Secrets battery** (`matrx_orm.secrets_battery`): the ONE canonical user-credential vault — `users.user_secrets` CRUD + the platform's single Fernet primitive, keyed by `CREDENTIALS_ENCRYPTION_KEY`. Any package: `configure_secrets(db_config_name=...)` once, then `await require_user_secret(user_id, key)`. No package ever calls another service to resolve a credential. Contract: [`matrx_orm/secrets_battery/FEATURE.md`](matrx_orm/secrets_battery/FEATURE.md).
 - **Polymorphic associations** (`matrx_orm.associations`): `EntityRegistry` (token→Model) + `Associations` — a registry-driven, **access-gated** edge engine over a host's polymorphic edge table. Every `source→target` hop is org-scoped *and* each resolved endpoint is re-authorized against the ACTOR (fail-closed, screams on a genuine leak), so a hop can't widen access past what the actor may reach. 🚨 **The gate is `access_check` (wire `matrx_orm.platform_access_check` → `iam.has_access_for`), NEVER an org-column comparison** — a person belongs to several orgs on purpose, so org-equality denies her own data across her own workspaces (2026-08-30 incident) while granting any co-member of a private row. The edge's `org_id` is a TENANCY stamp, not a permission. Org-equality survives only for UNATTENDED writes (no actor) as an integrity guard, and **system vocabulary is exempt entirely** (existence still required): a model generated with `_rls_variant="system"` is platform-shared dictionary data (seo.keyword/topic) every tenant legitimately links to. Hardcodes no table names — the host wires its own edge + token-registry models.
-- **The host's declared session context** (`matrx_orm.core.session_context`): `configure_session_context(provider)` once at startup, and every **top-level** `transaction()` — including the one `rls_session` opens, before it drops to the restricted role — emits whatever the provider returns as transaction-local GUCs. This is how an application-level declaration reaches Postgres at all: a GUC set outside a transaction has no meaning, so the BEGIN is the only place it can land. aidream wires it to its provenance declaration (`app.actor_tier` / `app.actor_system`, read by `platform.actor_tier()`, the history capture and the tier rule). A nested entry is a savepoint inside a transaction that already carries them and emits nothing — and a write made **outside** any transaction carries no declaration at all, which is why a single-row write that must record its author still opens one. No provider configured ⇒ no GUCs (standalone behaviour unchanged); a provider that raises fails the transaction loudly rather than committing rows with a false provenance.
+- **The host's declared session context** (`matrx_orm.core.session_context`): `configure_session_context(provider)` once at startup, and every **top-level** `transaction()` — including the one `rls_session` opens, before it drops to the restricted role — emits whatever the provider returns as transaction-local GUCs. This is how an application-level declaration reaches Postgres at all: a GUC set outside a transaction has no meaning, so the BEGIN is the only place it can land. aidream wires it to its provenance declaration (`app.actor_tier` / `app.actor_system`, read by `platform.actor_tier()`, the history capture and the tier rule). A nested entry is a savepoint inside a transaction that already carries them and emits nothing. A standalone write (`execute_write` outside any transaction) made while the provider has something to say opens its own transaction for that one statement — and still goes through the write queue, inside a copy of the caller's context, so the queue's concurrency gate is kept and the drain task's foreign context cannot hide the declaration (`tests/level1/test_standalone_write_session_context.py`). No provider configured ⇒ no GUCs (standalone behaviour unchanged); a provider that raises fails the transaction loudly rather than committing rows with a false provenance.
 - **The platform access policy** (`matrx_orm.platform_access`): `platform_access_check(actor, token, id, level)` → `iam.has_access_for`. The ONE answer to "may this actor touch this row?", shared with RLS and the file-access gate. Fails closed. Never re-derive it from `organization_id` or `created_by` — both are strict subsets that deny legitimate access.
 
 Public API is defined explicitly in `matrx_orm/__init__.py` (100+ exports). Treat changes there as semver-breaking.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.140
+Version: 3.1.142
 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.142}/matrx_orm/core/async_db_manager.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import contextvars
 from dataclasses import dataclass
 import json
 import logging
@@ -1605,25 +1606,46 @@ class AsyncDatabaseManager:
         except ImportError:
             pass
 
+        from matrx_orm.core.write_queue import get_write_queue_registry
+
+        config_name = resolve_database_name(config_name)
+        wq = get_write_queue_registry().get(config_name)
+
         # A declared host session context (notably actor provenance) is made of
         # transaction-local GUCs. A plain standalone write used to skip BEGIN,
         # so its trigger saw the database default even though the caller had
-        # explicitly declared an actor. Keep the declaration in the caller's
-        # task (the write-queue drain has a different ContextVar context) and
-        # use the canonical transaction path for this one write.
+        # explicitly declared an actor — so a declared write takes the
+        # canonical transaction path (BEGIN → GUCs → statement → COMMIT).
+        #
+        # It still goes through the write queue. The queue's drain executes
+        # each item in a task forked from the DRAIN's context, where the
+        # caller's ContextVar declaration is invisible; so the item is run
+        # inside a copy of the caller's context instead of skipping the
+        # queue. Skipping was the first fix (2026-09-12) and it was fine while
+        # only a few doors declared; once the request boundary declares for
+        # EVERY authenticated request, skipping would have moved every
+        # request write off the queue's concurrency gate and onto raw pool
+        # acquires — the pool-storm class the queue exists to prevent.
         from matrx_orm.core.session_context import session_context_gucs
 
         if session_context_gucs():
             from matrx_orm.core.transaction import transaction
 
-            config_name = resolve_database_name(config_name)
-            async with transaction(config_name):
-                return await cls.execute_query(config_name, query, *args, timeout=timeout)
+            async def _declared_write() -> list[dict[str, Any]]:
+                async with transaction(config_name):
+                    return await cls.execute_query(config_name, query, *args, timeout=timeout)
 
-        from matrx_orm.core.write_queue import get_write_queue_registry
+            if wq is None:
+                return await _declared_write()
 
-        config_name = resolve_database_name(config_name)
-        wq = get_write_queue_registry().get(config_name)
+            caller_context = contextvars.copy_context()
+
+            async def _in_caller_context() -> list[dict[str, Any]]:
+                # Awaited by the drain's item task; the inner task carries the
+                # caller's context so the session provider sees the declaration.
+                return await asyncio.create_task(_declared_write(), context=caller_context)
+
+            return await wq.submit(_in_caller_context)
 
         if wq is not None:
             return await wq.submit(

{matrx_orm-3.1.140 → matrx_orm-3.1.142}/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.142}/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.142}/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.142}/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()