matrx-orm 3.1.38__tar.gz → 3.1.40__tar.gz

{matrx_orm-3.1.38 → matrx_orm-3.1.40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrx-orm
-Version: 3.1.38
+Version: 3.1.40
 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.38 → matrx_orm-3.1.40}/matrx_orm/secrets_battery/FEATURE.md

@@ -37,16 +37,60 @@ row whose owner columns don't match its item's owner.
 `editable=false` blocks human value changes (`FieldNotEditableError`); the owning
 service rotates via `system_rotation=True` / `rotate_credential_fields`.
 
+**`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
+user could switch "inject into sandbox" on and get nothing, forever, with no
+error — the silent-failure class this guard ends. Three layers, each sufficient
+alone, each loud:
+
+1. **Write refusal** — `create_credential_bundle` / `add_credential_field` /
+   `update_field_metadata` raise `SandboxInjectionWithoutEnvKeyError` (a
+   `ValueError`, so hosts answer 422 with the reason). `update_field_metadata`
+   judges the POST-patch state, so *clearing the alias of an already-injecting
+   field* is refused the same way. Setting `env_key` and the flag in ONE patch
+   is the supported fix and always passes.
+2. **Resolution scream** — `_keyed_for_sandbox` logs an ERROR naming the row ids
+   and skips them, so anything that got in around layer 1 is visible.
+3. **DB CHECK** `user_secrets_sandbox_injection_needs_key` (migration 0265) makes
+   the state unrepresentable; the column default moved `true` → `false` so the
+   database stops manufacturing violations on keyless inserts.
+
 Item surface: `create_credential_item` · `create_credential_bundle` (item + N
 fields, ONE transaction) · `get/list/update/delete_credential_item` (delete =
 soft, atomic across item + fields + grants) · `add_credential_field` ·
 `update_credential_field_value` · `update_field_metadata` (metadata-only patch — value/version untouched; sealed is a one-way door: TO sealed ok, FROM sealed never; env-alias regex + per-principal uniqueness) · `rotate_credential_fields` (atomic multi-field)
 · `delete_credential_field` · stable resolution `resolve_field_by_id` /
 `resolve_field(item_id, field_key)` / `resolve_item_fields` · `reveal_field` ·
-`set_item_grants` / `list_item_grants` · `transfer_credential_item` (owner flip,
-no value copy, references survive) · `fork_credential_item` (independent copy) ·
-`resolve_legacy_env_key` (compat read that SCREAMS in logs until call sites
-migrate to stable references).
+`add_item_grant` / `update_item_grant` / `remove_item_grant` / `list_item_grants`
+· `set_item_grants` · `list_granted_credential_items` ·
+`transfer_credential_item` (owner flip, no value copy, references survive) ·
+`fork_credential_item` (independent copy) · `resolve_legacy_env_key` (compat
+read that SCREAMS in logs until call sites migrate to stable references).
+
+**Grants: use the single-grant operations.** `add_item_grant` /
+`update_item_grant` / `remove_item_grant` change ONE recipient and leave the
+rest alone. `set_item_grants` REPLACES the whole set (delete + recreate) and
+drops every grantee when `access_mode='all_members'` — it survives for the org
+access-mode flip, but building new callers on it is how a share edit silently
+revokes someone. `list_granted_credential_items(user_id)` is the
+"shared with me" read.
+
+`transfer_credential_item` clears prior grants by default (`clear_grants=True`)
+and writes BOTH `item_transferred` and `item_transferred_out`, so the losing
+owner's audit shows it too. Its `to_user_id` accepts any user — deciding who may
+transfer to whom (resolved from an exact email) is the HOST's job, per the
+battery's no-tenancy rule.
+
+**Destination-login metadata (2026-07-26, credential-sharing PLAN).** Items also
+carry PLAINTEXT, deliberately-unencrypted columns: `login_urls` (`text[]`),
+`uri_match_mode` (`host|exact|never`), `notes`, `non_secret_fields` (ordered
+`[{key,label,value}]`), `browser_fill_enabled`. This module validates their
+shape — URLs must be http/https, `non_secret_fields` keys match `FIELD_KEY_RE`
+and are unique, entries carry only `{key,label,value}` — because it is the only
+write path. `handling` does NOT apply to them: whether a value is encrypted is
+decided by the catalog field's `storage_class`, never by handling. Never move a
+secret into these columns to make it "easier to read".
 
 ## Consumer contract
 
@@ -93,7 +137,10 @@ EXCLUDES `sealed` fields, so a browser-facing caller can never receive sealed
 plaintext through an env dump. Only trusted execution (service-token sandbox
 injection, in-process context hydration, provider adapters) passes `True`.
 Rows with `key IS NULL` (item fields without an env alias) never resolve into
-an environment in either mode.
+an environment in either mode — silently when nothing promised otherwise (a
+keyless item field is normal), but **LOUDLY when `for_sandbox=True`**: such a row
+is flagged for injection and cannot deliver, which is a defect (see the
+handling doctrine above).
 
 **Legacy key-based writes respect item discipline:** `create_user_secret(upsert=True)`,
 `update_user_secret`, and `delete_user_secret` REFUSE a target row that is
@@ -191,6 +238,7 @@ create, reveal, sealed denial, editable gate, rotate, item grants, soft delete).
 
 ## Change Log
 
+- 2026-07-26 — Closed the silent sandbox-injection gap: `SandboxInjectionWithoutEnvKeyError` at every field write path, a loud ERROR-and-skip in `for_sandbox` bulk resolution, and DB CHECK `user_secrets_sandbox_injection_needs_key` (+ column default `true`→`false`). Live at the time of the fix: 0 broken rows, but 61 keyless item fields were one toggle away from it.
 - 2026-07-23 — `update_field_metadata` primitive (metadata-only, version-preserving; `users.bump_user_secret_value_version` verified value-conditional live — no trigger change needed).
 - 2026-07-23 — Adversarial-review hardening: include_sealed-aware bulk env resolution (+ keyless-row exclusion), ItemManagedSecretError legacy-write guards + legacy audit rows, ItemGrantSpec per-grantee grants, reveal liveness filters, rotate liveness re-check + audits inside owning transactions.
 - 2026-07-23 — Phase 2: item layer (`items.py` — bundles, handling modes, stable resolution, item grants, transfer/fork), rotation primitives (`fernet_for_key`/`multi_fernet_for_keys`) + `scripts/rotate_credentials_key.py` (closes the no-rotation-script ticket), migration 0236 grants fixup (item-level grants possible).

{matrx_orm-3.1.38 → matrx_orm-3.1.40}/matrx_orm/secrets_battery/__init__.py

@@ -41,14 +41,17 @@ from .items import (
     HANDLING_MODES,
     ITEM_SOURCES,
     ITEM_STATUSES,
+    URI_MATCH_MODES,
     CredentialFieldRow,
     CredentialItemNotFoundError,
     CredentialItemRow,
     FieldNotEditableError,
     FieldSpec,
     ItemGrantSpec,
+    SandboxInjectionWithoutEnvKeyError,
     SealedFieldError,
     add_credential_field,
+    add_item_grant,
     create_credential_bundle,
     create_credential_item,
     delete_credential_field,
@@ -56,7 +59,10 @@ from .items import (
     fork_credential_item,
     get_credential_item,
     list_credential_items,
+    list_granted_credential_items,
     list_item_grants,
+    remove_item_grant,
+    update_item_grant,
     resolve_field,
     resolve_field_by_id,
     resolve_item_fields,
@@ -145,8 +151,11 @@ __all__ = [
     "FieldNotEditableError",
     "FieldSpec",
     "ItemGrantSpec",
+    "SandboxInjectionWithoutEnvKeyError",
     "SealedFieldError",
+    "URI_MATCH_MODES",
     "add_credential_field",
+    "add_item_grant",
     "create_credential_bundle",
     "create_credential_item",
     "delete_credential_field",
@@ -154,7 +163,10 @@ __all__ = [
     "fork_credential_item",
     "get_credential_item",
     "list_credential_items",
+    "list_granted_credential_items",
     "list_item_grants",
+    "remove_item_grant",
+    "update_item_grant",
     "resolve_field",
     "resolve_field_by_id",
     "resolve_item_fields",

{matrx_orm-3.1.38 → matrx_orm-3.1.40}/matrx_orm/secrets_battery/items.py

@@ -42,6 +42,7 @@ snake, stable semantic identity of a field within its item."""
 
 HANDLING_MODES: tuple[str, ...] = ("visible", "revealable", "sealed")
 ITEM_STATUSES: tuple[str, ...] = ("active", "disabled", "expired", "pending_verification")
+URI_MATCH_MODES: tuple[str, ...] = ("host", "exact", "never")
 ITEM_SOURCES: tuple[str, ...] = (
     "manual",
     "env_import",
@@ -68,6 +69,18 @@ class FieldNotEditableError(PermissionError):
     (``rotate_credential_fields``), never by hand."""
 
 
+class SandboxInjectionWithoutEnvKeyError(ValueError):
+    """``inject_into_sandbox=true`` on a field that has no environment-variable
+    alias (``key``). A container environment is a NAME→value map: with no name
+    the value has nowhere to land, so the flag is a promise the platform cannot
+    keep — the field would silently never appear in any sandbox.
+
+    Refused LOUDLY at every write path instead of accepted-and-dropped (hosts
+    map ``ValueError`` → 422). Set an env alias in the same request (the vault
+    field-metadata patch takes ``env_key`` and ``inject_into_sandbox``
+    together) or leave injection off."""
+
+
 # ── Shapes ────────────────────────────────────────────────────────────────
 
 
@@ -137,6 +150,13 @@ class CredentialItemRow:
     source: str
     access_mode: str
     lifecycle: dict[str, Any]
+    # Destination-login PLAINTEXT metadata (credential-sharing PLAN, 2026-07-26).
+    # Deliberately unencrypted; protected by the same ownership/grant/org RLS.
+    login_urls: list[str]
+    uri_match_mode: str
+    notes: str | None
+    non_secret_fields: list[dict[str, str]]
+    browser_fill_enabled: bool
     created_by: str | None
     updated_by: str | None
     created_at: str
@@ -167,6 +187,66 @@ def _validate_handling(handling: str) -> None:
         raise ValueError(f"handling must be one of {HANDLING_MODES}; got {handling!r}")
 
 
+def _validate_sandbox_injectable(
+    *,
+    field_key: str | None,
+    env_key: str | None,
+    inject_into_sandbox: bool,
+) -> None:
+    """LAYER 1 of the no-silent-injection guard: a field may only be flagged
+    for sandbox injection while it carries an env alias. See
+    :class:`SandboxInjectionWithoutEnvKeyError`. Layer 2 is the loud skip in
+    ``org_service`` bulk resolution; layer 3 is the DB CHECK
+    ``user_secrets_sandbox_injection_needs_key``."""
+    if inject_into_sandbox and not env_key:
+        raise SandboxInjectionWithoutEnvKeyError(
+            f"field {field_key or '<unnamed>'!r} cannot be injected into sandboxes without "
+            "an environment-variable alias (env_key) — a container env has no name to bind "
+            "the value to, so the flag would silently do nothing. Set env_key in the same "
+            "request, or leave inject_into_sandbox off."
+        )
+
+
+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}")
+
+
+def _validate_login_urls(urls: list[str]) -> None:
+    if not isinstance(urls, list):
+        raise ValueError("login_urls must be a list of URLs")
+    for url in urls:
+        if not isinstance(url, str) or not url.strip():
+            raise ValueError("login_urls entries must be non-empty strings")
+        lowered = url.strip().lower()
+        if not (lowered.startswith("https://") or lowered.startswith("http://")):
+            raise ValueError(f"login URL must start with https:// or http://; got {url!r}")
+
+
+def _validate_non_secret_fields(entries: list[dict[str, str]]) -> None:
+    """Ordered plaintext ``{key, label, value}`` entries. The DB pins the array
+    container; the exact entry shape is pinned here (the only write path)."""
+    if not isinstance(entries, list):
+        raise ValueError("non_secret_fields must be a list")
+    seen: set[str] = set()
+    for entry in entries:
+        if not isinstance(entry, dict):
+            raise ValueError("each non_secret_fields entry must be an object")
+        extra = set(entry) - {"key", "label", "value"}
+        if extra:
+            raise ValueError(f"non_secret_fields entry has unknown keys {sorted(extra)}")
+        key = entry.get("key")
+        if not isinstance(key, str) or not re.match(FIELD_KEY_RE, key):
+            raise ValueError(f"non_secret_fields entry key must match {FIELD_KEY_RE}; got {key!r}")
+        if key in seen:
+            raise ValueError(f"duplicate non_secret_fields key {key!r}")
+        seen.add(key)
+        if not isinstance(entry.get("label"), str) or not entry["label"]:
+            raise ValueError(f"non_secret_fields entry {key!r} needs a non-empty label")
+        if not isinstance(entry.get("value"), str):
+            raise ValueError(f"non_secret_fields entry {key!r} value must be a string")
+
+
 def _iso(value: Any) -> str:
     if isinstance(value, datetime):
         return value.isoformat()
@@ -187,6 +267,11 @@ _ITEM_FIELDS = (
     "source",
     "access_mode",
     "lifecycle",
+    "login_urls",
+    "uri_match_mode",
+    "notes",
+    "non_secret_fields",
+    "browser_fill_enabled",
     "created_by",
     "updated_by",
     "created_at",
@@ -225,6 +310,11 @@ def _item_row(raw: dict[str, Any], fields: list[CredentialFieldRow]) -> Credenti
         source=str(raw["source"]),
         access_mode=str(raw.get("access_mode") or "all_members"),
         lifecycle=dict(raw.get("lifecycle") or {}),
+        login_urls=list(raw.get("login_urls") or []),
+        uri_match_mode=str(raw.get("uri_match_mode") or "host"),
+        notes=raw.get("notes"),
+        non_secret_fields=list(raw.get("non_secret_fields") or []),
+        browser_fill_enabled=bool(raw.get("browser_fill_enabled", False)),
         created_by=str(raw["created_by"]) if raw.get("created_by") else None,
         updated_by=str(raw["updated_by"]) if raw.get("updated_by") else None,
         created_at=_iso(raw["created_at"]),
@@ -275,6 +365,33 @@ async def _require_item_raw(item_id: str) -> dict[str, Any]:
 # ── Item CRUD ─────────────────────────────────────────────────────────────
 
 
+def _metadata_kwargs(
+    *,
+    login_urls: list[str] | None,
+    uri_match_mode: str | None,
+    notes: str | None,
+    non_secret_fields: list[dict[str, str]] | None,
+    browser_fill_enabled: bool | None,
+) -> dict[str, Any]:
+    """Validate + shape the destination-login plaintext metadata for a create.
+    Omitted (None) values fall back to the column defaults."""
+    out: dict[str, Any] = {}
+    if login_urls is not None:
+        _validate_login_urls(login_urls)
+        out["login_urls"] = [u.strip() for u in login_urls]
+    if uri_match_mode is not None:
+        _validate_uri_match_mode(uri_match_mode)
+        out["uri_match_mode"] = uri_match_mode
+    if notes is not None:
+        out["notes"] = notes
+    if non_secret_fields is not None:
+        _validate_non_secret_fields(non_secret_fields)
+        out["non_secret_fields"] = non_secret_fields
+    if browser_fill_enabled is not None:
+        out["browser_fill_enabled"] = bool(browser_fill_enabled)
+    return out
+
+
 async def create_credential_item(
     *,
     user_id: str | None = None,
@@ -288,6 +405,11 @@ async def create_credential_item(
     source: str = "manual",
     access_mode: str = "all_members",
     lifecycle: dict[str, Any] | None = None,
+    login_urls: list[str] | None = None,
+    uri_match_mode: str | None = None,
+    notes: str | None = None,
+    non_secret_fields: list[dict[str, str]] | None = None,
+    browser_fill_enabled: bool | None = None,
     actor_id: str | None = None,
 ) -> CredentialItemRow:
     """Create an empty item (no fields). Prefer :func:`create_credential_bundle`
@@ -310,6 +432,13 @@ async def create_credential_item(
         source=source,
         access_mode=access_mode,
         lifecycle=lifecycle or {},
+        **_metadata_kwargs(
+            login_urls=login_urls,
+            uri_match_mode=uri_match_mode,
+            notes=notes,
+            non_secret_fields=non_secret_fields,
+            browser_fill_enabled=browser_fill_enabled,
+        ),
         created_by=actor_id,
         updated_by=actor_id,
     )
@@ -340,6 +469,11 @@ async def create_credential_bundle(
     source: str = "manual",
     access_mode: str = "all_members",
     lifecycle: dict[str, Any] | None = None,
+    login_urls: list[str] | None = None,
+    uri_match_mode: str | None = None,
+    notes: str | None = None,
+    non_secret_fields: list[dict[str, str]] | None = None,
+    browser_fill_enabled: bool | None = None,
     actor_id: str | None = None,
 ) -> CredentialItemRow:
     """**The atomic create path**: item + N encrypted fields in ONE
@@ -355,6 +489,11 @@ async def create_credential_bundle(
     for spec in fields:
         _validate_field_key(spec.field_key)
         _validate_handling(spec.handling)
+        _validate_sandbox_injectable(
+            field_key=spec.field_key,
+            env_key=spec.env_key,
+            inject_into_sandbox=spec.inject_into_sandbox,
+        )
         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:
@@ -375,6 +514,13 @@ async def create_credential_bundle(
             source=source,
             access_mode=access_mode,
             lifecycle=lifecycle or {},
+            **_metadata_kwargs(
+                login_urls=login_urls,
+                uri_match_mode=uri_match_mode,
+                notes=notes,
+                non_secret_fields=non_secret_fields,
+                browser_fill_enabled=browser_fill_enabled,
+            ),
             created_by=actor_id,
             updated_by=actor_id,
         )
@@ -457,9 +603,16 @@ async def update_credential_item(
     status: str | None = None,
     provider_key: str | None = None,
     lifecycle: dict[str, Any] | None = None,
+    login_urls: list[str] | None = None,
+    uri_match_mode: str | None = None,
+    notes: Any = None,
+    clear_notes: bool = False,
+    non_secret_fields: list[dict[str, str]] | None = None,
+    browser_fill_enabled: bool | None = None,
 ) -> CredentialItemRow:
-    """Patch item metadata. ``None`` fields are left alone. Values live on the
-    field rows — this never touches ciphertext."""
+    """Patch item metadata. ``None`` fields are left alone (``clear_notes=True``
+    nulls the plaintext notes). Values live on the field rows — this never
+    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}")
     updates: dict[str, Any] = {"updated_by": actor_id, "updated_at": datetime.now(UTC)}
@@ -475,6 +628,17 @@ async def update_credential_item(
         updates["provider_key"] = provider_key
     if lifecycle is not None:
         updates["lifecycle"] = lifecycle
+    updates.update(
+        _metadata_kwargs(
+            login_urls=login_urls,
+            uri_match_mode=uri_match_mode,
+            notes=None if clear_notes else notes,
+            non_secret_fields=non_secret_fields,
+            browser_fill_enabled=browser_fill_enabled,
+        )
+    )
+    if clear_notes:
+        updates["notes"] = None
     result = await CredentialItem.update_where(
         {"id": item_id, "deleted_at__isnull": True}, **updates
     )
@@ -540,6 +704,11 @@ async def add_credential_field(
     the item so field-level scoping stays consistent)."""
     _validate_field_key(spec.field_key)
     _validate_handling(spec.handling)
+    _validate_sandbox_injectable(
+        field_key=spec.field_key,
+        env_key=spec.env_key,
+        inject_into_sandbox=spec.inject_into_sandbox,
+    )
     if not isinstance(spec.value, str):
         raise ValueError("value must be a string")
     raw = await _require_item_raw(item_id)
@@ -710,6 +879,19 @@ async def update_field_metadata(
                 "a one-way door; rotate/replace the field instead of unsealing it"
             )
 
+        # The POST-patch state is what matters: enabling injection on a keyless
+        # field AND clearing the alias of an already-injecting field are the
+        # same silent breakage from opposite directions. Both are refused.
+        _validate_sandbox_injectable(
+            field_key=raw.get("field_key") or raw.get("key"),
+            env_key=(raw.get("key") if env_key is _UNSET else env_key),
+            inject_into_sandbox=(
+                bool(raw.get("inject_into_sandbox"))
+                if inject_into_sandbox is None
+                else inject_into_sandbox
+            ),
+        )
+
         updates: dict[str, Any] = {"updated_by": actor_id, "updated_at": datetime.now(UTC)}
         if inject_into_sandbox is not None:
             updates["inject_into_sandbox"] = inject_into_sandbox
@@ -1000,20 +1182,188 @@ async def list_item_grants(item_id: str) -> list[dict[str, Any]]:
     ]
 
 
+async def add_item_grant(
+    item_id: str,
+    *,
+    user_id: str,
+    can_use: bool = True,
+    can_manage: bool = False,
+    actor_id: str | None = None,
+) -> dict[str, Any]:
+    """Add (or refresh) ONE item-level grant without touching any other
+    recipient — the explicit-operation replacement for the destructive
+    ``set_item_grants`` overwrite. The HOST verifies the actor may share and
+    that the recipient is legitimate first."""
+    if not user_id:
+        raise ValueError("grant user_id is required")
+    await _require_item_raw(item_id)
+    existing = await UserSecretGrant.filter(
+        credential_item_id=item_id, user_id=user_id
+    ).values("id")
+    if existing:
+        grant_id = str(existing[0]["id"])
+        await UserSecretGrant.update_where(
+            {"id": grant_id},
+            can_use=can_use,
+            can_manage=can_manage,
+            granted_by=actor_id,
+        )
+        action = "grant_changed"
+    else:
+        instance = await UserSecretGrant.create(
+            credential_item_id=item_id,
+            user_secret_id=None,
+            user_id=user_id,
+            can_use=can_use,
+            can_manage=can_manage,
+            granted_by=actor_id,
+        )
+        grant_id = str(instance.id)
+        action = "grant_added"
+    await record_secret_audit(
+        action=action,
+        actor_id=actor_id,
+        metadata={
+            "credential_item_id": item_id,
+            "grant_id": grant_id,
+            "recipient_user_id": user_id,
+            "can_use": can_use,
+            "can_manage": can_manage,
+        },
+    )
+    rows = await UserSecretGrant.filter(id=grant_id).values(
+        "id", "user_id", "can_use", "can_manage", "granted_by", "created_at"
+    )
+    r = rows[0]
+    return {
+        "id": str(r["id"]),
+        "user_id": str(r["user_id"]),
+        "can_use": bool(r["can_use"]),
+        "can_manage": bool(r["can_manage"]),
+        "granted_by": str(r["granted_by"]) if r.get("granted_by") else None,
+        "created_at": _iso(r["created_at"]),
+    }
+
+
+async def update_item_grant(
+    item_id: str,
+    grant_id: str,
+    *,
+    can_use: bool | None = None,
+    can_manage: bool | None = None,
+    actor_id: str | None = None,
+) -> dict[str, Any]:
+    """Change ONE grant's capabilities. The grant must belong to the item
+    (path binding — same rule as fields)."""
+    rows = await UserSecretGrant.filter(id=grant_id, credential_item_id=item_id).values(
+        "id", "user_id", "can_use", "can_manage"
+    )
+    if not rows:
+        raise LookupError(f"grant {grant_id} not found")
+    updates: dict[str, Any] = {}
+    if can_use is not None:
+        updates["can_use"] = can_use
+    if can_manage is not None:
+        updates["can_manage"] = can_manage
+    if updates:
+        await UserSecretGrant.update_where({"id": grant_id}, **updates)
+    await record_secret_audit(
+        action="grant_changed",
+        actor_id=actor_id,
+        metadata={
+            "credential_item_id": item_id,
+            "grant_id": grant_id,
+            "recipient_user_id": str(rows[0]["user_id"]),
+            "can_use": updates.get("can_use", bool(rows[0]["can_use"])),
+            "can_manage": updates.get("can_manage", bool(rows[0]["can_manage"])),
+        },
+    )
+    out = await UserSecretGrant.filter(id=grant_id).values(
+        "id", "user_id", "can_use", "can_manage", "granted_by", "created_at"
+    )
+    r = out[0]
+    return {
+        "id": str(r["id"]),
+        "user_id": str(r["user_id"]),
+        "can_use": bool(r["can_use"]),
+        "can_manage": bool(r["can_manage"]),
+        "granted_by": str(r["granted_by"]) if r.get("granted_by") else None,
+        "created_at": _iso(r["created_at"]),
+    }
+
+
+async def remove_item_grant(
+    item_id: str,
+    grant_id: str,
+    *,
+    actor_id: str | None = None,
+) -> None:
+    """Revoke ONE grant. Effective immediately — the RLS grantee policies and
+    every capability check key on the row's existence."""
+    rows = await UserSecretGrant.filter(id=grant_id, credential_item_id=item_id).values(
+        "id", "user_id"
+    )
+    if not rows:
+        raise LookupError(f"grant {grant_id} not found")
+    await UserSecretGrant.delete_where(id=grant_id)
+    await record_secret_audit(
+        action="revoked",
+        actor_id=actor_id,
+        metadata={
+            "credential_item_id": item_id,
+            "grant_id": grant_id,
+            "recipient_user_id": str(rows[0]["user_id"]),
+        },
+    )
+
+
+async def list_granted_credential_items(user_id: str) -> list[CredentialItemRow]:
+    """Items shared TO ``user_id`` through item-level grants (``can_use``),
+    with masked fields — the backend twin of the frontend's grants-driven
+    "Shared with me" query."""
+    if not user_id:
+        raise ValueError("user_id is required")
+    grant_rows = await UserSecretGrant.filter(
+        user_id=user_id, credential_item_id__isnull=False, can_use=True
+    ).values("credential_item_id")
+    item_ids = sorted({str(r["credential_item_id"]) for r in grant_rows})
+    if not item_ids:
+        return []
+    rows = (
+        await CredentialItem.filter(id__in=item_ids, deleted_at__isnull=True)
+        .order_by("display_name")
+        .values(*_ITEM_FIELDS)
+    )
+    if not rows:
+        return []
+    fields = await _fields_for_items([str(r["id"]) for r in rows])
+    return [_item_row(r, fields.get(str(r["id"]), [])) for r in rows]
+
+
 async def transfer_credential_item(
     item_id: str,
     *,
     to_user_id: str | None = None,
     to_organization_id: str | None = None,
     actor_id: str | None = None,
+    clear_grants: bool = True,
 ) -> CredentialItemRow:
     """Move ownership in ONE audited transaction — item and every field flip
     owner together, and every stable reference (item id, field ids, field
-    keys) survives unchanged. No value is copied or re-encrypted."""
+    keys) survives unchanged. No value is copied or re-encrypted. Prior
+    personal grants are CLEARED by default (a transfer is a clean handover,
+    not a share), and both the old and the new owner get an audit entry."""
     _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):
+        cleared = 0
+        if clear_grants:
+            grant_rows = await UserSecretGrant.filter(credential_item_id=item_id).values("id")
+            cleared = len(grant_rows)
+            await UserSecretGrant.delete_where(credential_item_id=item_id)
         await CredentialItem.update_where(
             {"id": item_id, "deleted_at__isnull": True},
             user_id=to_user_id,
@@ -1028,18 +1378,27 @@ async def transfer_credential_item(
             updated_by=actor_id,
             updated_at=now,
         )
+        transfer_meta = {
+            "credential_item_id": item_id,
+            "from_user_id": from_user_id,
+            "from_organization_id": from_organization_id,
+            "to_user_id": to_user_id,
+            "to_organization_id": to_organization_id,
+            "grants_cleared": cleared,
+        }
         await record_secret_audit(
             action="item_transferred",
             actor_id=actor_id,
             organization_id=to_organization_id,
             user_id=to_user_id,
-            metadata={
-                "credential_item_id": 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,
-            },
+            metadata=transfer_meta,
+        )
+        await record_secret_audit(
+            action="item_transferred_out",
+            actor_id=actor_id,
+            organization_id=from_organization_id,
+            user_id=from_user_id,
+            metadata=transfer_meta,
         )
     item = await get_credential_item(item_id)
     if item is None:  # pragma: no cover
@@ -1077,6 +1436,11 @@ async def fork_credential_item(
             source=raw["source"],
             access_mode="all_members",
             lifecycle={**dict(raw.get("lifecycle") or {}), "forked_from": item_id},
+            login_urls=list(raw.get("login_urls") or []),
+            uri_match_mode=str(raw.get("uri_match_mode") or "host"),
+            notes=raw.get("notes"),
+            non_secret_fields=list(raw.get("non_secret_fields") or []),
+            browser_fill_enabled=bool(raw.get("browser_fill_enabled", False)),
             created_by=actor_id,
             updated_by=actor_id,
         )
@@ -1148,6 +1512,7 @@ __all__ = [
     "FieldNotEditableError",
     "FieldSpec",
     "ItemGrantSpec",
+    "SandboxInjectionWithoutEnvKeyError",
     "SealedFieldError",
     "add_credential_field",
     "create_credential_bundle",