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

{matrx_orm-3.1.209 → matrx_orm-3.1.211}/CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md — matrx-orm
 
-> 🟢 **RETIREMENT DECIDED 2026-08-22:** this package is being replaced by SQLAlchemy 2 + Alembic under a thin opinion layer and extracted to its own repo. Cross-repo system-of-record: /Users/armanisadeghi/code/common-docs/projects/orm-switch/PLAN.md — read it before touching this feature in ANY repo.
+> 🟢 **RETIREMENT DECIDED 2026-08-22:** this package is being replaced by SQLAlchemy 2 + Alembic under a thin opinion layer and extracted to its own repo. Cross-repo system-of-record: /Users/armanisadeghi/code/common-docs/systems/architecture/database/orm-persistence/projects/orm-switch/PLAN.md — read it before touching this feature in ANY repo.
 
 > **Operating Principle: Build the platform, not the artifact.** Every task is a probe that exposes a missing capability — build it, then consume it. Code that only serves one artifact is forbidden. Full doctrine: [/PRINCIPLES.md](../../PRINCIPLES.md).
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.209
+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.209 → matrx_orm-3.1.211}/matrx_orm/secrets_battery/FEATURE.md

@@ -1,6 +1,6 @@
 # matrx-orm secrets battery — the ONE credential vault
 
-> Cross-repo plan (implementation authority): `/Users/armanisadeghi/code/common-docs/projects/unified-credential-vault/PLAN.md` — read it before expanding credential storage or package resolution in any repository. Phase 1 (schema) + Phase 2 (this battery's item layer, rotation script, unified aidream service) are live.
+> Cross-repo plan (implementation authority): `/Users/armanisadeghi/code/common-docs/systems/account/vault-secrets/FEATURE.md` — read it before expanding credential storage or package resolution in any repository. Phase 1 (schema) + Phase 2 (this battery's item layer, rotation script, unified aidream service) are live.
 
 **One table, one key, everywhere.** Every platform credential — personal AND
 organizational — lives in `users.user_secrets` (Fernet-encrypted). Every package
@@ -84,7 +84,7 @@ ownership/shape helper and does not decrypt.
 
 **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.
 
-**Native lifecycle component (`native_lifecycle.py`).** The shared coordinator must supply locked parent/child projections from the exported field constants, current host management authority and its active transaction. Inspection locks the exact native metadata child; component delete/restore mutate only that child's tombstone and lifecycle. Deletion accepts active and restored-quarantined sources; recovery compares aware ISO manifest timestamps to database timestamps, then parses the already-validated manifest instant only at the typed native restore mutation boundary. Personal metadata provenance is enforced by the database guard, never inferred from the request scope. Coordinator/preview integration and actual aggregate database acceptance remain pending; these helpers alone do not enable protected recovery. Contract: [native lifecycle](../../../../../common-docs/projects/credential-sharing-browser-login/NATIVE-LIFECYCLE.md).
+**Native lifecycle component (`native_lifecycle.py`).** The shared coordinator must supply locked parent/child projections from the exported field constants, current host management authority and its active transaction. Inspection locks the exact native metadata child; component delete/restore mutate only that child's tombstone and lifecycle. Deletion accepts active and restored-quarantined sources; recovery compares aware ISO manifest timestamps to database timestamps, then parses the already-validated manifest instant only at the typed native restore mutation boundary. Personal metadata provenance is enforced by the database guard, never inferred from the request scope. Coordinator/preview integration and actual aggregate database acceptance remain pending; these helpers alone do not enable protected recovery. Contract: [native lifecycle](../../../../../common-docs/projects/credential-sharing-browser-login/REGISTER.md).
 
 **`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

{matrx_orm-3.1.209 → 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.209 → 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
@@ -55,7 +55,7 @@ copied into a fork.
 A field lands here when possessing it MINTS future access rather than merely
 holding a value someone already gave you — an authenticator seed generates
 every future code for the account, forever, with nothing recording it. D-15
-(``common-docs/projects/persistent-cloud-browser/DECISIONS.md``) ruled that a
+(``common-docs/systems/architecture/persistent-cloud-browser/VISION.md``) ruled that a
 seed does not travel with an account handover: the new owner enrols again.
 
 🚨 This is deliberately NOT "every ``sealed`` field". Sealed also covers OAuth
@@ -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.209 → matrx_orm-3.1.211}/pyproject.toml

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

{matrx_orm-3.1.209 → matrx_orm-3.1.211}/tests/test_secrets_minting_keys.py

@@ -1,6 +1,6 @@
 """Minting keys never change hands — D-15, enforced in the battery (no DB).
 
-``common-docs/projects/persistent-cloud-browser/DECISIONS.md`` D-15: *"A seed
+``common-docs/systems/architecture/persistent-cloud-browser/VISION.md`` D-15: *"A seed
 does NOT transfer with an account handover — the new owner enrolls again.
 Otherwise two people generate valid codes forever with nothing recording it."*