matrx-orm 3.1.148__tar.gz → 3.1.150__tar.gz

{matrx_orm-3.1.148 → matrx_orm-3.1.150}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.148
+Version: 3.1.150
 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.40
+Requires-Dist: matrx-utils>=2.0.41
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

{matrx_orm-3.1.148 → matrx_orm-3.1.150}/matrx_orm/secrets_battery/__init__.py

@@ -80,6 +80,7 @@ from .items import (
     FieldSpec,
     ItemGrantSpec,
     SandboxInjectionWithoutEnvKeyError,
+    SealedBrowserFillPasswordError,
     SealedFieldError,
     TransferResult,
     add_credential_field,
@@ -215,6 +216,7 @@ __all__ = [
     "FieldSpec",
     "ItemGrantSpec",
     "SandboxInjectionWithoutEnvKeyError",
+    "SealedBrowserFillPasswordError",
     "SealedFieldError",
     "URI_MATCH_MODES",
     "add_credential_field",

{matrx_orm-3.1.148 → matrx_orm-3.1.150}/matrx_orm/secrets_battery/items.py

@@ -110,6 +110,21 @@ class SandboxInjectionWithoutEnvKeyError(ValueError):
     together) or leave injection off."""
 
 
+class SealedBrowserFillPasswordError(ValueError):
+    """A ``password`` field is (or would become) ``handling='sealed'`` on an
+    item with ``browser_fill_enabled=true``. A sealed value has NO reveal
+    path anywhere — including the browser-fill boundary itself
+    (``vault.py`` ``_prepare_fill_payload`` / ``vault_resolve_for_browser``
+    both refuse a sealed field with "is sealed and cannot be filled into a
+    page"), so a browser-fill login built this way can never actually fill
+    a page: it looks saved but is permanently unusable.
+
+    Refused LOUDLY at every write path instead of accepted-and-broken —
+    'revealable' is the canonical handling for a browser-fill password: it
+    still requires reveal capability + recent auth to resolve, but (unlike
+    'sealed') it is allowed to cross the browser-fill boundary at all."""
+
+
 class ProtectedSecretPurposeError(PermissionError):
     """A generic path reached a native-provider-only secret before decrypt."""
 
@@ -255,6 +270,24 @@ def _validate_sandbox_injectable(
         )
 
 
+def _refuse_sealed_browser_fill_password(
+    *, browser_fill_enabled: bool, field_key: str, handling: str
+) -> None:
+    """Catch the sealed/browser-fill contradiction at the write boundary —
+    see :class:`SealedBrowserFillPasswordError`. Scoped to the ``password``
+    field key: that is the one the browser-fill path actually needs, and
+    the one the live incident hit (a ``website_login`` created with a
+    sealed password was silently unusable)."""
+    if browser_fill_enabled and field_key == "password" and handling == "sealed":
+        raise SealedBrowserFillPasswordError(
+            "field 'password' cannot be handling='sealed' on an item with "
+            "browser_fill_enabled=true — a sealed value is refused at fill "
+            "time, so this login would be saved but could never actually "
+            "fill a page. Use handling='revealable' for a browser-fill "
+            "login instead."
+        )
+
+
 def _validate_uri_match_mode(mode: str) -> None:
     if mode not in URI_MATCH_MODES:
         raise ValueError(f"uri_match_mode must be one of {URI_MATCH_MODES}; got {mode!r}")
@@ -588,6 +621,11 @@ async def create_credential_bundle(
             env_key=spec.env_key,
             inject_into_sandbox=spec.inject_into_sandbox,
         )
+        _refuse_sealed_browser_fill_password(
+            browser_fill_enabled=bool(browser_fill_enabled),
+            field_key=spec.field_key,
+            handling=spec.handling,
+        )
         if not isinstance(spec.value, str):
             raise ValueError(f"field {spec.field_key!r}: value must be a string")
         if spec.field_key in seen:
@@ -709,6 +747,21 @@ async def update_credential_item(
     touches ciphertext."""
     if status is not None and status not in ITEM_STATUSES:
         raise ValueError(f"status must be one of {ITEM_STATUSES}; got {status!r}")
+    if browser_fill_enabled:
+        sealed_password = await UserSecret.filter(
+            credential_item_id=item_id,
+            field_key="password",
+            handling="sealed",
+            is_active=True,
+            deleted_at__isnull=True,
+        ).values("id")
+        if sealed_password:
+            raise SealedBrowserFillPasswordError(
+                "cannot set browser_fill_enabled=true — this item's 'password' field is "
+                "handling='sealed', which is refused at fill time, so the login would be "
+                "saved but could never actually fill a page. Rotate/replace the password "
+                "field with handling='revealable' first."
+            )
     updates: dict[str, Any] = {"updated_by": actor_id, "updated_at": datetime.now(UTC)}
     if display_name is not None:
         updates["display_name"] = display_name
@@ -827,6 +880,11 @@ async def add_credential_field(
         raise ValueError("value must be a string")
     async with transaction(PACKAGE_DB_NAME):
         raw = await _lock_item_raw(item_id)
+        _refuse_sealed_browser_fill_password(
+            browser_fill_enabled=bool(raw.get("browser_fill_enabled")),
+            field_key=spec.field_key,
+            handling=spec.handling,
+        )
         instance = await UserSecret.create(
             user_id=raw.get("user_id"),
             organization_id=raw.get("organization_id"),
@@ -999,8 +1057,9 @@ async def update_field_metadata(
         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")
+        item_raw: dict[str, Any] | None = None
         if rows[0].get("credential_item_id"):
-            await _lock_item_raw(str(rows[0]["credential_item_id"]))
+            item_raw = 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"
         )
@@ -1014,6 +1073,12 @@ async def update_field_metadata(
                 f"field {raw.get('field_key') or raw.get('key')!r} is sealed — sealing is "
                 "a one-way door; rotate/replace the field instead of unsealing it"
             )
+        if handling is not None:
+            _refuse_sealed_browser_fill_password(
+                browser_fill_enabled=bool((item_raw or {}).get("browser_fill_enabled")),
+                field_key=str(raw.get("field_key") or ""),
+                handling=handling,
+            )
 
         # The POST-patch state is what matters: enabling injection on a keyless
         # field AND clearing the alias of an already-injecting field are the

{matrx_orm-3.1.148 → matrx_orm-3.1.150}/matrx_orm/session/README.md

@@ -273,6 +273,15 @@ printed (`storm: … suppressed …`), and folded into the next admitted row as
 `context._storm.suppressed_in_previous_window`. Nothing is lost, nothing floods.
 Guard: `tests/session/test_record_error_storm.py`.
 
+If the bounded `ops.system_error` insert itself times out or meets a lock, the
+fallback emits exactly one `matrx_orm_system_error_capture_failed` ERROR event.
+Its `matrx_system_error` metadata keeps the original kind/error, request and route,
+plus a bounded, secret-redacted original traceback, the capture exception and operation.
+It never copies the failed capture's payload or context into that app-log event. Do not
+add a `vcprint` banner beside that event: `vcprint` is also captured by the app-log
+handler and would turn one failed capture into two unrelated error families. Guard:
+`tests/session/test_record_error_bounded_insert.py`.
+
 ## Telemetry (optional)
 
 If OpenTelemetry is installed, Session emits spans and metrics:

{matrx_orm-3.1.148 → matrx_orm-3.1.150}/matrx_orm/session/fallback.py

@@ -28,6 +28,7 @@ from typing import Any
 from uuid import UUID
 
 from matrx_utils import vcprint
+from matrx_utils.secret_detection import redact_secrets
 
 from matrx_orm.exceptions import describe_db_exception
 from matrx_orm.session.op import SessionOp
@@ -70,6 +71,11 @@ STORM_ROW_BUDGET = 3
 CAPTURE_ACQUIRE_TIMEOUT_SECONDS = 2.0
 CAPTURE_LOCK_TIMEOUT_MS = 1500
 CAPTURE_STATEMENT_TIMEOUT_MS = 2500
+# A failed error capture cannot make the forensic diagnostic itself an
+# unbounded durable log payload.  This bound is deliberately below app_log's
+# generic message cap because this is a last-resort, high-frequency path.
+CAPTURE_FAILURE_DIAGNOSTIC_MAX = 8_192
+CAPTURE_FAILURE_DIAGNOSTIC_TRUNCATION_MARKER = "… [truncated]"
 _storm_state: dict[tuple[str, str, str], dict[str, Any]] = {}
 
 
@@ -147,6 +153,17 @@ def _serialize_primary_key(pk_field: str, pk_value: str) -> str:
     return json.dumps({pk_field: pk_value})
 
 
+def _capture_failure_diagnostic(value: object) -> str:
+    """Redact and bound text retained when ``system_error`` capture fails."""
+    redacted, _ = redact_secrets(str(value))
+    if len(redacted) <= CAPTURE_FAILURE_DIAGNOSTIC_MAX:
+        return redacted
+    prefix_length = CAPTURE_FAILURE_DIAGNOSTIC_MAX - len(
+        CAPTURE_FAILURE_DIAGNOSTIC_TRUNCATION_MARKER
+    )
+    return redacted[:prefix_length] + CAPTURE_FAILURE_DIAGNOSTIC_TRUNCATION_MARKER
+
+
 def _safe_uuid(value: Any) -> str | None:
     """Return ``value`` only if it is a valid UUID, else ``None``.
 
@@ -724,27 +741,29 @@ async def record_error(
             color="yellow",
         )
     except Exception as capture_exc:
-        # Last resort — the capture itself failed. Don't let it crash the
-        # caller (we're usually already on an error/cancel path). Scream.
-        vcprint(
-            "\n"
-            "╔══════════════════════════════════════════════════════════════════╗\n"
-            "║  matrx-orm — system_error capture FAILED                         ║\n"
-            "╚══════════════════════════════════════════════════════════════════╝\n"
-            f"  kind:        {kind}\n"
-            f"  error:       {resolved_error_text}\n"
-            f"  capture exc: {type(capture_exc).__name__}: {capture_exc}\n"
-            f"  traceback:\n{tb_text}",
-            color="red",
-        )
+        # ``vcprint(..., color="red")`` is itself a logger call.  Emitting it
+        # beside this structured event made ONE failed capture appear as TWO
+        # unrelated ERROR families in ``app_log``.  Keep one ERROR so the
+        # durable log has an exact, queryable incident without concealing the
+        # original failure or the bounded-capture refusal.
         logger.error(
             "matrx_orm_system_error_capture_failed",
             extra={
                 "matrx_system_error": {
                     "kind": kind,
-                    "error_text": resolved_error_text,
+                    "error_type": resolved_error_type,
+                    "error_text": _capture_failure_diagnostic(resolved_error_text),
                     "request_id": request_id,
                     "user_id": user_id,
+                    "route": route,
+                    "capture_exception_type": type(capture_exc).__name__,
+                    "capture_exception_text": _capture_failure_diagnostic(capture_exc),
+                    "capture_operation": "ops.system_error.insert",
+                    # Do not include the original payload or context here: either
+                    # can contain request secrets.  This traceback is the bounded,
+                    # redacted diagnostic that lets the one surviving app-log event
+                    # retain the original failure boundary instead.
+                    "original_traceback": _capture_failure_diagnostic(tb_text),
                 }
             },
         )

{matrx_orm-3.1.148 → matrx_orm-3.1.150}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.148"
+version = "3.1.150"
 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.40",
+    "matrx-utils>=2.0.41",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",

{matrx_orm-3.1.148 → matrx_orm-3.1.150}/tests/session/test_record_error_bounded_insert.py

@@ -14,6 +14,8 @@ set AFTER the INSERT (too late to protect anything).
 
 from __future__ import annotations
 
+import logging
+
 import pytest
 
 from matrx_orm.session import fallback
@@ -87,3 +89,67 @@ async def test_capture_insert_is_bounded_before_it_touches_the_table(monkeypatch
     assert log[1] == f"SET LOCAL statement_timeout = '{fallback.CAPTURE_STATEMENT_TIMEOUT_MS}ms'"
     assert log[2].startswith("INSERT INTO ops.system_error")
     assert len(log) == 3
+
+
+@pytest.mark.asyncio
+async def test_failed_capture_emits_one_structured_error_not_a_banner_twin(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    """One failed insert must remain one durable app-log incident."""
+
+    capture_secret = "sk-" + "a" * 32
+    traceback_sentinel = "TRACEBACK_SENTINEL"
+
+    async def _failed_insert(**_kwargs) -> None:
+        raise RuntimeError(f"lock timeout API_TOKEN={capture_secret}")
+
+    def _unexpected_banner(*_args, **_kwargs) -> None:
+        raise AssertionError("capture failure must not make a second vcprint log event")
+
+    monkeypatch.setattr(fallback, "_insert_error", _failed_insert)
+    monkeypatch.setattr(fallback, "vcprint", _unexpected_banner)
+
+    with caplog.at_level(logging.ERROR, logger="matrx_orm.session.fallback"):
+        await fallback.record_error(
+            ValueError("shed"),
+            kind="cloud_file_change_feed_shed",
+            request_id="request-1",
+            user_id="user-1",
+            route="/api/cloud-files/changes",
+            traceback_text=f"{traceback_sentinel}\nAPI_TOKEN={capture_secret}",
+            payload={"access_token": capture_secret},
+            context={"credential": capture_secret},
+        )
+
+    records = [
+        record
+        for record in caplog.records
+        if record.name == "matrx_orm.session.fallback"
+        and record.getMessage() == "matrx_orm_system_error_capture_failed"
+    ]
+    assert len(records) == 1
+    captured = records[0].matrx_system_error
+    assert captured == {
+        "kind": "cloud_file_change_feed_shed",
+        "error_type": "ValueError",
+        "error_text": "ValueError: shed",
+        "request_id": "request-1",
+        "user_id": "user-1",
+        "route": "/api/cloud-files/changes",
+        "capture_exception_type": "RuntimeError",
+        "capture_exception_text": "lock timeout API_TOKEN=<redacted:token>",
+        "capture_operation": "ops.system_error.insert",
+        "original_traceback": f"{traceback_sentinel}\nAPI_TOKEN=<redacted:API_TOKEN>",
+    }
+    assert capture_secret not in repr(captured)
+
+
+def test_capture_failure_diagnostic_is_bounded_and_secret_safe() -> None:
+    secret = "sk-" + "b" * 32
+    diagnostic = fallback._capture_failure_diagnostic(
+        f"API_TOKEN={secret}\n" + "x" * (fallback.CAPTURE_FAILURE_DIAGNOSTIC_MAX + 1)
+    )
+
+    assert secret not in diagnostic
+    assert diagnostic.endswith("… [truncated]")
+    assert len(diagnostic) <= fallback.CAPTURE_FAILURE_DIAGNOSTIC_MAX

{matrx_orm-3.1.148 → matrx_orm-3.1.150}/tests/test_secrets_battery.py

@@ -923,3 +923,96 @@ def test_error_taxonomy():
     assert issubclass(SealedFieldError, PermissionError)
     assert issubclass(FieldNotEditableError, PermissionError)
     assert issubclass(CredentialItemNotFoundError, LookupError)
+
+
+# ── Sealed password on a browser-fill item (live incident: a website_login
+# created with handling='sealed' was accepted, then unusable — vault.py's
+# browser-fill path refuses any sealed field at fill time) ─────────────────
+
+
+def test_refuse_sealed_browser_fill_password_helper():
+    """Direct coverage of the boundary check: only the exact combination
+    (browser_fill_enabled AND field_key == 'password' AND handling ==
+    'sealed') is refused — every other combination is fine."""
+    from matrx_orm.secrets_battery.items import (
+        SealedBrowserFillPasswordError,
+        _refuse_sealed_browser_fill_password,
+    )
+
+    with pytest.raises(SealedBrowserFillPasswordError, match="cannot be handling='sealed'"):
+        _refuse_sealed_browser_fill_password(
+            browser_fill_enabled=True, field_key="password", handling="sealed"
+        )
+
+    # A sealed field that is not 'password' does not collide with browser fill.
+    _refuse_sealed_browser_fill_password(
+        browser_fill_enabled=True, field_key="totp_seed", handling="sealed"
+    )
+    # A sealed password is fine when the item never fills into a browser.
+    _refuse_sealed_browser_fill_password(
+        browser_fill_enabled=False, field_key="password", handling="sealed"
+    )
+    # 'revealable' is exactly the handling the browser-fill path accepts.
+    _refuse_sealed_browser_fill_password(
+        browser_fill_enabled=True, field_key="password", handling="revealable"
+    )
+
+
+def test_create_credential_bundle_refuses_sealed_password_with_browser_fill_enabled():
+    """RED before the fix: a website_login created with browser_fill_enabled
+    plus a sealed password field used to be accepted silently and was then
+    permanently unfillable (vault.py ~1741 'is sealed and cannot be filled
+    into a page'). All field validation in create_credential_bundle runs
+    BEFORE the DB transaction opens, so this raises with no DB configured —
+    proof the refusal happens at the write boundary, not deep in a query."""
+    import asyncio
+
+    from matrx_orm.secrets_battery import FieldSpec
+    from matrx_orm.secrets_battery.items import (
+        SealedBrowserFillPasswordError,
+        create_credential_bundle,
+    )
+
+    with pytest.raises(SealedBrowserFillPasswordError, match="password.*browser_fill_enabled"):
+        asyncio.run(
+            create_credential_bundle(
+                user_id="u1",
+                display_name="AI Matrx",
+                browser_fill_enabled=True,
+                login_urls=["https://www.aimatrx.com/login"],
+                fields=[
+                    FieldSpec("username", "me@example.com"),
+                    FieldSpec("password", "hunter2", handling="sealed"),
+                ],
+            )
+        )
+
+
+def test_create_credential_bundle_validation_accepts_revealable_password():
+    """The canonical fix: 'revealable' clears the same validation loop and
+    the function proceeds past field validation toward the DB transaction
+    (which then fails for lack of a configured database in this DB-free
+    test) — proof the guard targets 'sealed' specifically, not every
+    browser-fill password."""
+    import asyncio
+
+    from matrx_orm.secrets_battery import FieldSpec
+    from matrx_orm.secrets_battery.items import (
+        SealedBrowserFillPasswordError,
+        create_credential_bundle,
+    )
+
+    with pytest.raises(Exception) as excinfo:
+        asyncio.run(
+            create_credential_bundle(
+                user_id="u1",
+                display_name="AI Matrx",
+                browser_fill_enabled=True,
+                login_urls=["https://www.aimatrx.com/login"],
+                fields=[
+                    FieldSpec("username", "me@example.com"),
+                    FieldSpec("password", "hunter2", handling="revealable"),
+                ],
+            )
+        )
+    assert not isinstance(excinfo.value, SealedBrowserFillPasswordError)