matrx-orm 3.1.210__tar.gz → 3.1.211__tar.gz

{matrx_orm-3.1.210 → matrx_orm-3.1.211}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.210
+Version: 3.1.211
 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

{matrx_orm-3.1.210 → matrx_orm-3.1.211}/matrx_orm/secrets_battery/crypto.py

@@ -255,6 +255,21 @@ def mask_value(plaintext: str) -> str:
     return f"{plaintext[:head_len]}…{plaintext[-head_len:]}"
 
 
+def hint_for(handling: str | None, plaintext: str) -> str:
+    """The ``value_hint`` a stored field may carry: ``mask_value`` for a field a person may see
+    again, and NOTHING for a ``sealed`` one.
+
+    A sealed field is a value nobody can ever read back — a connection string, an authenticator
+    seed — and its hint goes to every client that lists the item. ``postg…uire`` is eight
+    characters of a secret handed to a browser (lane VISION-REACH, verifier 2026-10-03); the
+    first and last four of a connection string are its scheme and its ``sslmode``, but the
+    rule is the class, not the sample: no character of a sealed value leaves the server.
+    """
+    if handling == "sealed":
+        return ""
+    return mask_value(plaintext)
+
+
 __all__ = [
     "configure_encryption",
     "fernet_for_key",
@@ -270,4 +285,5 @@ __all__ = [
     "derive_hmac_key",
     "keyed_digest",
     "mask_value",
+    "hint_for",
 ]

{matrx_orm-3.1.210 → matrx_orm-3.1.211}/matrx_orm/secrets_battery/items.py

@@ -30,7 +30,7 @@ from typing import Any
 
 from matrx_orm import transaction
 
-from .crypto import decrypt_value, encrypt_value, mask_value
+from .crypto import decrypt_value, encrypt_value, hint_for
 from .host_authorization import CAPABILITY_MANAGE, require_host_authorization
 from .model import PACKAGE_DB_NAME, CredentialAttachment, CredentialItem, UserSecret, UserSecretGrant
 from .org_service import audit_organization, record_secret_audit
@@ -739,7 +739,7 @@ async def create_credential_bundle(
                 field_key=spec.field_key,
                 key=spec.env_key,
                 value_encrypted=encrypt_value(spec.value),
-                value_hint=mask_value(spec.value),
+                value_hint=hint_for(spec.handling, spec.value),
                 handling=spec.handling,
                 editable=spec.editable,
                 inject_into_sandbox=spec.inject_into_sandbox,
@@ -1270,7 +1270,7 @@ async def add_credential_field(
             field_key=spec.field_key,
             key=spec.env_key,
             value_encrypted=encrypt_value(spec.value),
-            value_hint=mask_value(spec.value),
+            value_hint=hint_for(spec.handling, spec.value),
             handling=spec.handling,
             editable=spec.editable,
             inject_into_sandbox=spec.inject_into_sandbox,
@@ -1435,7 +1435,7 @@ async def update_credential_field_value(
         await UserSecret.update_where(
             {"id": field_id, "deleted_at__isnull": True},
             value_encrypted=encrypted_value,
-            value_hint=mask_value(value),
+            value_hint=hint_for(str(raw.get("handling") or ""), value),
             updated_by=actor_id,
             updated_at=datetime.now(UTC),
         )
@@ -1512,7 +1512,7 @@ async def rotate_credential_fields(
             await UserSecret.update_where(
                 {"id": str(field_raw["id"])},
                 value_encrypted=encrypted_value,
-                value_hint=mask_value(plaintext),
+                value_hint=hint_for(str(field_raw.get("handling") or ""), plaintext),
                 updated_by=actor_id,
                 updated_at=now,
             )

{matrx_orm-3.1.210 → matrx_orm-3.1.211}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.210"
+version = "3.1.211"
 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" }

matrx_orm-3.1.211/tests/test_a_sealed_field_shows_no_character_of_its_value.py

@@ -0,0 +1,51 @@
+"""A SEALED FIELD'S value_hint IS EMPTY — no character of a secret reaches a client (lane VISION-REACH wave 3).
+
+THE USE CASE: Cedar Ridge Physical Therapy connects its own Postgres to AI Matrx. The connection string
+is a SEALED vault field (nobody can ever reveal it), yet every vault listing carried its ``value_hint`` —
+``postg…uire`` — eight characters of the secret, to every browser that opened the item (verifier,
+2026-10-03). The hint is the only value-derived data a field row may carry, so it is the one thing to
+guard: sealed → nothing; anything a person may see again → the masked shape as before.
+
+The census below reads the battery's own write paths: every ``value_hint=`` a UserSecret write sets
+goes through ``hint_for``; a new write that reaches for ``mask_value`` directly is a new member of the
+class and turns this red.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+from matrx_orm.secrets_battery import crypto
+
+CONNECTION = "postgresql://clinic_reader:Sentinel-Pw-7f3a9c@aws-0-us-east-1.pooler.supabase.com:6543/postgres?sslmode=require"
+TOKEN = "ghp_1234567890abcd"
+
+
+@pytest.mark.parametrize(
+    ("handling", "value", "expected"),
+    [
+        ("sealed", CONNECTION, ""),
+        ("sealed", TOKEN, ""),
+        ("revealable", TOKEN, "ghp_…abcd"),
+        ("visible", "clinic_reader", "clin…ader"),
+        (None, TOKEN, "ghp_…abcd"),
+    ],
+)
+def test_the_hint_of_a_field_is_nothing_when_sealed_and_the_mask_otherwise(handling, value, expected) -> None:
+    hint = crypto.hint_for(handling, value)
+    assert hint == expected
+    if handling == "sealed":
+        assert not any(ch in hint for ch in value if ch not in "…")
+
+
+def test_every_value_hint_the_battery_writes_goes_through_hint_for() -> None:
+    """CENSUS (not a change detector): the class is 'a UserSecret write that sets value_hint'."""
+    source = Path(crypto.__file__).with_name("items.py").read_text()
+    # a WRITE derives the hint from a plaintext; a projection copies the row's own column back out
+    writes = [w for w in re.findall(r"value_hint=([^,\n]+)", source) if '"value_hint"' not in w]
+    assert len(writes) >= 4, f"items.py writes value_hint in fewer places than the four it had: {writes}"
+    direct = [w for w in writes if not w.startswith("hint_for(")]
+    assert direct == [], f"a value_hint written without hint_for: {direct}"