matrx-orm 3.1.25__tar.gz → 3.1.26__tar.gz

{matrx_orm-3.1.25 → matrx_orm-3.1.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.25
+Version: 3.1.26
 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.25 → matrx_orm-3.1.26}/matrx_orm/core/async_db_manager.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+from dataclasses import dataclass
 import json
 import logging
 import os
@@ -285,6 +286,15 @@ _init_connection = _init_connection_default
 _init_vector_codec = _init_connection_default
 
 
+@dataclass(frozen=True, slots=True)
+class ConnectionIdentity:
+    """The role/database a pool is actually connected as."""
+
+    current_user: str
+    session_user: str
+    database: str
+
+
 class AsyncDatabaseManager:
     _instance = None
     _pools = {}
@@ -496,6 +506,30 @@ class AsyncDatabaseManager:
                         ) from e
             return cls._pools[config_name]
 
+    @classmethod
+    async def connection_identity(cls, config_name: str) -> ConnectionIdentity:
+        """Who is this pool actually connected AS.
+
+        Exists so a service can PROVE it is inside its granted database
+        boundary (`current_user` = its scoped role) without hand-writing SQL —
+        the question "which role am I?" is database introspection, which the
+        ORM owns. Postgres exposes `current_user` / `session_user` /
+        `current_database` as reserved keywords rather than callable
+        functions, so `call_function` cannot reach them; this is the sanctioned
+        accessor.
+        """
+        pool = await cls.get_pool(config_name)
+        async with pool.acquire() as conn:
+            row = await conn.fetchrow(
+                "SELECT current_user AS current_user, session_user AS session_user, "
+                "current_database() AS database"
+            )
+        return ConnectionIdentity(
+            current_user=row["current_user"],
+            session_user=row["session_user"],
+            database=row["database"],
+        )
+
     @classmethod
     def _start_keepalive(cls, config_name: str, pool_min: int) -> None:
         """Start (or restart) the per-config pool keepalive task.

matrx_orm-3.1.26/matrx_orm/secrets_battery/FEATURE.md

@@ -0,0 +1,112 @@
+# matrx-orm secrets battery — the ONE credential vault
+
+**One table, one key, everywhere.** Every platform credential — personal AND
+organizational — lives in `users.user_secrets` (Fernet-encrypted). Every package
+and deployment that needs a credential holds the same `CREDENTIALS_ENCRYPTION_KEY`
+and reads the vault directly through this module. **No package calls another
+package or a service to resolve a credential** — there is no privileged
+decryptor (decided 2026-07-21; doctrine: `docs/packages/PACKAGE_DOCTRINE.md` §5).
+
+There is no second vault. The `private_vault.organization_secrets` system
+(Supabase Vault, decryption inside Postgres) was **annihilated 2026-07-21** —
+schema, tables, SECURITY DEFINER functions, and the duplicated `vault.secrets`
+material all dropped. A new `Fernet(...)` or a second secrets table anywhere is
+a defect.
+
+## Consumer contract
+
+```python
+from matrx_orm.secrets_battery import require_secret
+api_key = await require_secret(user_id, organization_id, "DATAFORSEO_API_KEY")
+```
+
+**`require_secret` is the one you want.** It implements the hierarchy:
+**personal → organization → raise**, naming both scopes it searched. Most people
+never hold their own API keys — their organization does.
+
+`require_user_secret(user_id, key)` is the personal-only variant. Both raise
+`SecretNotFoundError` / `SecretDecryptError` and never return None;
+`get_user_secret` / `get_org_secret` are the degradable twins.
+
+## Scope — one table, two shapes
+
+A row is PERSONAL (`user_id` set, `organization_id` NULL) or ORG-SCOPED
+(`organization_id` set, `user_id` NULL). A DB CHECK enforces exactly one, and
+partial unique indexes make `(scope, key)` unique among live rows.
+
+| Surface | Personal | Org |
+|---|---|---|
+| read one | `get_user_secret` | `get_org_secret` |
+| read many | — | `resolve_org_secrets` |
+| hierarchy (one key) | `require_secret` | ← same call |
+| hierarchy (many keys) | `resolve_effective_secrets` | ← same call |
+| CRUD | `create/update/delete_user_secret` | `create/update/delete_org_secret` |
+| listing | `list_user_secrets` | `list_org_secrets` |
+| grants | — | `set_org_secret_grants` |
+
+**Precedence is the same in both directions:** a PERSONAL value wins over an org
+value on key collision. `require_secret` checks personal first;
+`resolve_effective_secrets` loads org values then overlays personal on top. They
+are two expressions of one rule — keep them that way.
+
+## Grants and access modes
+
+An org secret is `access_mode='all_members'` (default) or `'restricted'`.
+A restricted secret is readable only by a user holding a `can_use` row in
+`users.user_secret_grants` — **or by an org admin**, via the `is_org_admin`
+flag the host computes and passes down.
+
+## The authorization boundary — read this before adding a check here
+
+**matrx-orm has no tenancy model and must never grow one.** This module does NOT
+decide who is a member or an admin of an organization. The HOST asserts that and
+passes the outcome in as `is_org_admin`. What the battery DOES own is the
+per-secret grant check, because `user_secret_grants` is its own table.
+
+aidream's authorization layer is
+[`aidream/services/user_secrets/organizations.py`](../../../../aidream/services/user_secrets/organizations.py):
+membership → `iam.has_org_access_for`, adminhood → `public.is_org_admin_for`,
+asserted before the battery is touched.
+
+## Audit
+
+`users.user_secret_audit` records **actions and metadata, NEVER values**
+(`record_secret_audit`). Audit is a trail, not a transaction: a failed audit
+write is logged loudly but never fails the operation the user asked for —
+losing the trail must not also lose the work.
+
+## Wiring
+
+- **Hosted:** `configure_secrets(db_config_name="<registered config>")` at
+  startup (aidream: `package_integration.py`) — aliases `matrx_secrets` onto the
+  host pool. One physical pool.
+- **Standalone package/service:** register your DB with matrx-orm, call the same
+  `configure_secrets`. Key comes from `CREDENTIALS_ENCRYPTION_KEY` env, or pass
+  `encryption_key=` (host injection).
+- Key resolution (byte-identical to the historical aidream implementation — all
+  existing ciphertexts keep decrypting): explicit key → `CREDENTIALS_ENCRYPTION_KEY`
+  (44-char urlsafe-base64 used directly, else SHA-256-derived) → `SUPABASE_SECRET_KEY`
+  derivation with a loud warning → loud RuntimeError.
+
+## Invariants
+
+- **This is the only Fernet instance in the universe.** The dict-payload helpers
+  (`encrypt_payload`/`decrypt_payload`) serve `tool.mcp_user_conn` blobs — same
+  key, same instance.
+- Every read is scoped by a **required** `user_id` or `organization_id`. No None
+  = "show everything".
+- Soft delete by default (`deleted_at`); the partial unique indexes back the
+  upserts.
+- `value_hint` is the only value-derived field that may reach a listing/UI.
+  Listing and management surfaces are value-free by construction.
+- `value_version` is bumped by the `users.user_secrets_value_version` DB trigger
+  when `value_encrypted` changes — never by hand.
+- Rotating an org secret's value CLEARS its personal-secret lineage
+  (`source_user_secret_id`) — the org value is no longer what the contributor holds.
+- One unreadable row (key drift) is skipped with a loud log during bulk
+  resolution — a broken row must not deny every other key.
+
+Drift guard: `scripts/validate_secrets_decrypt.py` (loud, non-blocking, in
+`release.sh`) asserts every active row still decrypts with the configured key.
+
+Verified against live code + the live `users.user_secrets` schema 2026-07-21.

{matrx_orm-3.1.25 → matrx_orm-3.1.26}/matrx_orm/secrets_battery/__init__.py

@@ -34,7 +34,21 @@ from .crypto import (
     mask_value,
     reset_encryption_for_tests,
 )
-from .model import PACKAGE_DB_NAME, UserSecret
+from .model import PACKAGE_DB_NAME, UserSecret, UserSecretAudit, UserSecretGrant
+from .org_service import (
+    ACCESS_MODES,
+    OrgSecretRow,
+    create_org_secret,
+    delete_org_secret,
+    get_org_secret_row,
+    list_org_secrets,
+    record_secret_audit,
+    resolve_effective_secrets,
+    resolve_org_secrets,
+    set_org_secret_grants,
+    sync_org_secret_from_user,
+    update_org_secret,
+)
 from .service import (
     KNOWN_CATEGORIES,
     VALID_KEY_RE,
@@ -47,6 +61,8 @@ from .service import (
     get_user_secret,
     list_user_secrets,
     parse_env_text,
+    get_org_secret,
+    require_secret,
     require_user_secret,
     update_user_secret,
 )
@@ -87,7 +103,21 @@ __all__ = [
     "decrypt_payload",
     "mask_value",
     "UserSecret",
+    "UserSecretGrant",
+    "UserSecretAudit",
     "PACKAGE_DB_NAME",
+    "ACCESS_MODES",
+    "OrgSecretRow",
+    "create_org_secret",
+    "delete_org_secret",
+    "get_org_secret_row",
+    "list_org_secrets",
+    "record_secret_audit",
+    "resolve_effective_secrets",
+    "resolve_org_secrets",
+    "set_org_secret_grants",
+    "sync_org_secret_from_user",
+    "update_org_secret",
     "SecretRow",
     "SecretNotFoundError",
     "SecretDecryptError",
@@ -95,6 +125,8 @@ __all__ = [
     "VALID_KEY_RE",
     "list_user_secrets",
     "get_user_secret",
+    "require_secret",
+    "get_org_secret",
     "require_user_secret",
     "create_user_secret",
     "update_user_secret",

matrx_orm-3.1.26/matrx_orm/secrets_battery/model.py

@@ -0,0 +1,93 @@
+"""Package-owned model for the canonical vault table ``users.user_secrets``.
+
+Bound to the ``matrx_secrets`` config name (an alias): hosts point it at their
+already-registered pool via ``configure_secrets(db_config_name=...)`` — one
+physical pool, no second connection. ``user_id`` is a plain UUID column here
+(the DB enforces the FK to ``auth.users``) so the battery needs no host models.
+"""
+
+from __future__ import annotations
+
+from matrx_orm import (
+    BinaryField,
+    BooleanField,
+    DateTimeField,
+    IntegerField,
+    JSONBField,
+    Model,
+    TextField,
+    UUIDField,
+    model_registry,
+)
+
+PACKAGE_DB_NAME = "matrx_secrets"
+
+
+class UserSecret(Model):
+    """One vault row. PERSONAL (user_id set, organization_id NULL) or
+    ORG-SCOPED (organization_id set, user_id NULL) — never both."""
+
+    id = UUIDField(primary_key=True, null=False)
+    user_id = UUIDField()
+    organization_id = UUIDField()
+    created_by = UUIDField()
+    updated_by = UUIDField()
+    access_mode = TextField(null=False, default="all_members")
+    source_user_secret_id = UUIDField()
+    source_user_secret_version = IntegerField()
+    key = TextField(null=False)
+    value_encrypted = BinaryField(null=False)
+    value_hint = TextField()
+    description = TextField()
+    category = TextField()
+    is_active = BooleanField(null=False, default=True)
+    inject_into_sandbox = BooleanField(null=False, default=True)
+    last_used_at = DateTimeField()
+    created_at = DateTimeField(null=False)
+    updated_at = DateTimeField(null=False)
+    deleted_at = DateTimeField()
+    value_version = IntegerField(null=False, default=1)
+
+    _table_name = "user_secrets"
+    _db_schema = "users"
+    _database = PACKAGE_DB_NAME
+
+
+class UserSecretGrant(Model):
+    """Per-user grant for an ``access_mode='restricted'`` org secret."""
+
+    id = UUIDField(primary_key=True, null=False)
+    user_secret_id = UUIDField(null=False)
+    user_id = UUIDField(null=False)
+    can_use = BooleanField(null=False, default=True)
+    can_manage = BooleanField(null=False, default=False)
+    granted_by = UUIDField()
+    created_at = DateTimeField(null=False)
+    updated_at = DateTimeField(null=False)
+
+    _table_name = "user_secret_grants"
+    _db_schema = "users"
+    _database = PACKAGE_DB_NAME
+
+
+class UserSecretAudit(Model):
+    """Access/management trail. Records actions and metadata, NEVER values.
+    HIPAA §164.312(b) audit controls are required, not addressable."""
+
+    id = IntegerField(primary_key=True, null=False)
+    user_secret_id = UUIDField()
+    organization_id = UUIDField()
+    user_id = UUIDField()
+    actor_id = UUIDField()
+    action = TextField(null=False)
+    metadata = JSONBField(null=False, default={})
+    created_at = DateTimeField(null=False)
+
+    _table_name = "user_secret_audit"
+    _db_schema = "users"
+    _database = PACKAGE_DB_NAME
+
+
+model_registry.register_all([UserSecret, UserSecretGrant, UserSecretAudit], skip_existing=True)
+
+__all__ = ["UserSecret", "UserSecretGrant", "UserSecretAudit", "PACKAGE_DB_NAME"]