memwal 0.2.1__tar.gz → 0.2.2.dev0__tar.gz

{memwal-0.2.1 → memwal-0.2.2.dev0}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # memwal
 
+## 0.2.2
+
+Unreleased.
+
+### Added
+
+- `MemWal.destroy()` and `MemWalSync.destroy()` (plus `close(clear_keys=True)`) zero the client's internal `bytearray` seed copy in place, clear `_private_key_hex`, drop `_signing_key` and cached SEAL session credentials, cancel in-flight initialization tasks, and reject any subsequent or in-flight operation with `MemWalError`. `MemWal.create()` and `MemWalSync.create()` also accept 32-byte `bytes` / `bytearray` keys and copy caller `bytearray` buffers so `destroy()` leaves the caller's buffer intact. (#975)
+
+### Fixed
+
+- Shield shared `_build_seal_session` and `_resolve_owner` initialization tasks with `asyncio.shield`, clear the shared task slot via a completion callback that consumes exceptions on orphaned tasks, and cancel/drain in-flight initialization tasks in `close()` so cancelling one concurrent caller does not abort sibling callers or leave unretrieved task exceptions. (#1029)
+
 ## 0.2.1
 
 Unreleased.

{memwal-0.2.1 → memwal-0.2.2.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memwal
-Version: 0.2.1
+Version: 0.2.2.dev0
 Summary: Python SDK for Walrus Memory — Privacy-first AI memory with Ed25519 signing
 Project-URL: Homepage, https://memory.walrus.xyz
 Project-URL: Documentation, https://memory.walrus.xyz
@@ -259,6 +259,16 @@ Create a new async client.
 | `await remember_manual(opts)` | Store encrypted payload + pre-computed vector |
 | `await recall_manual(opts)` | Search with pre-computed vector |
 | `await get_public_key_hex()` | Get Ed25519 public key |
+| `destroy()` | Zero internal key seed buffer, drop signing credentials/session cache, and permanently invalidate the client |
+| `await close(clear_keys=False)` | Close the underlying HTTP client (pass `clear_keys=True` to also run `destroy()`) |
+
+### Key Lifecycle & `destroy()`
+
+For parity with the TypeScript SDK's `destroy()`, `MemWal` and `MemWalSync` expose `destroy()` and `close(clear_keys=True)`:
+
+- `key` may be passed as a hex string, `suiprivkey1...` string, or a 32-byte `bytes` / `bytearray`. When passed as `bytearray`, the SDK copies the bytes into its own internal buffer so `destroy()` zeroes only the client's copy and leaves the caller's `bytearray` untouched.
+- Calling `destroy()` (or `await client.close(clear_keys=True)` / `sync_client.close(clear_keys=True)`) zero-fills the client's internal `bytearray` seed copy in place, clears `_private_key_hex`, drops the `_signing_key` and cached SEAL session references, cancels any in-flight initialization tasks, and causes subsequent or in-flight calls to raise `MemWalError`.
+- **CPython memory semantics**: Python `str` and `bytes` objects (and PyNaCl's internal C-level `SigningKey` buffers) are immutable in CPython and cannot be overwritten in place from pure Python. `destroy()` zeroes the mutable `bytearray` copy and drops all references to immutable key objects so they become eligible for garbage collection once the caller also releases its references. To minimize plaintext `str` copies in process memory, pass a 32-byte `bytearray` to `MemWal.create()` and zero your own buffer after creation.
 
 ## Authentication
 

{memwal-0.2.1 → memwal-0.2.2.dev0}/README.md

@@ -218,6 +218,16 @@ Create a new async client.
 | `await remember_manual(opts)` | Store encrypted payload + pre-computed vector |
 | `await recall_manual(opts)` | Search with pre-computed vector |
 | `await get_public_key_hex()` | Get Ed25519 public key |
+| `destroy()` | Zero internal key seed buffer, drop signing credentials/session cache, and permanently invalidate the client |
+| `await close(clear_keys=False)` | Close the underlying HTTP client (pass `clear_keys=True` to also run `destroy()`) |
+
+### Key Lifecycle & `destroy()`
+
+For parity with the TypeScript SDK's `destroy()`, `MemWal` and `MemWalSync` expose `destroy()` and `close(clear_keys=True)`:
+
+- `key` may be passed as a hex string, `suiprivkey1...` string, or a 32-byte `bytes` / `bytearray`. When passed as `bytearray`, the SDK copies the bytes into its own internal buffer so `destroy()` zeroes only the client's copy and leaves the caller's `bytearray` untouched.
+- Calling `destroy()` (or `await client.close(clear_keys=True)` / `sync_client.close(clear_keys=True)`) zero-fills the client's internal `bytearray` seed copy in place, clears `_private_key_hex`, drops the `_signing_key` and cached SEAL session references, cancels any in-flight initialization tasks, and causes subsequent or in-flight calls to raise `MemWalError`.
+- **CPython memory semantics**: Python `str` and `bytes` objects (and PyNaCl's internal C-level `SigningKey` buffers) are immutable in CPython and cannot be overwritten in place from pure Python. `destroy()` zeroes the mutable `bytearray` copy and drops all references to immutable key objects so they become eligible for garbage collection once the caller also releases its references. To minimize plaintext `str` copies in process memory, pass a 32-byte `bytearray` to `MemWal.create()` and zero your own buffer after creation.
 
 ## Authentication
 

{memwal-0.2.1 → memwal-0.2.2.dev0}/memwal/__init__.py

@@ -128,4 +128,4 @@ __all__ = [
     "RecallManualResult",
 ]
 
-__version__ = "0.2.1"
+__version__ = "0.2.2.dev0"

{memwal-0.2.1 → memwal-0.2.2.dev0}/memwal/client.py

@@ -437,6 +437,12 @@ def _check_vector(vector: Any) -> None:
     ):
         raise ValueError("vector must be a non-empty list of finite numbers")
 
+def _destroyed_client_error() -> "MemWalError":
+    return MemWalError(
+        "Walrus Memory client was destroyed; its keys are zeroed. Create a new one."
+    )
+
+
 class MemWal:
     """Async-native Walrus Memory client.
 
@@ -445,8 +451,13 @@ class MemWal:
     """
 
     def __init__(self, config: MemWalConfig) -> None:
-        self._private_key_hex = normalize_private_key(config.key)
-        self._signing_key = build_signing_key(self._private_key_hex)
+        self._destroyed: bool = False
+        self._private_key_hex: str = normalize_private_key(config.key)
+        signing_key = build_signing_key(self._private_key_hex)
+        self._signing_key: Optional[nacl.signing.SigningKey] = signing_key
+        # Mutable copy of the 32-byte seed so destroy() can zero-fill it in
+        # place without mutating any caller-supplied bytearray (#975).
+        self._private_key_bytes: bytearray = bytearray(bytes(signing_key))
         self._account_id = config.account_id
         self._server_url = normalize_server_url(config.server_url)
         self._namespace = config.namespace
@@ -473,7 +484,7 @@ class MemWal:
     @classmethod
     def create(
         cls,
-        key: str,
+        key: Union[str, bytes, bytearray],
         account_id: str,
         server_url: Optional[str] = None,
         namespace: str = "default",
@@ -482,7 +493,10 @@ class MemWal:
         """Create a new Walrus Memory client instance.
 
         Args:
-            key: Ed25519 private key hex string (the delegate key).
+            key: Ed25519 private key (hex string, ``suiprivkey1...``, or 32-byte
+                ``bytes`` / ``bytearray``). When passed as ``bytearray``, the
+                bytes are copied into an internal buffer so :meth:`destroy`
+                zeroes only the client's copy and leaves the caller's buffer intact.
             account_id: Walrus Memory account object ID on Sui.
             server_url: Server URL (default: ``https://relayer.memory.walrus.xyz``).
             namespace: Default namespace for memory isolation (default: ``"default"``).
@@ -510,8 +524,65 @@ class MemWal:
             self._client = httpx.AsyncClient(timeout=60.0)
         return self._client
 
-    async def close(self) -> None:
-        """Close the underlying HTTP client."""
+    def destroy(self) -> None:
+        """Wipe internal key buffers, drop signing credentials, and invalidate the client.
+
+        Provides parity with the TypeScript SDK's ``destroy()`` method (#975):
+
+        - Zeroes ``_private_key_bytes`` (the client's internal ``bytearray`` seed
+          copy) in place.
+        - Clears ``_private_key_hex``, drops the ``_signing_key`` reference, and
+          clears cached SEAL session tokens, server config, owner address, and
+          pending idempotency keys.
+        - Marks the client as destroyed so any subsequent or in-flight operation
+          raises :class:`MemWalError`.
+
+        Note on CPython memory semantics:
+            Python ``str`` and ``bytes`` objects (and PyNaCl's internal C-level
+            ``SigningKey`` buffers) are immutable in CPython and cannot be zeroed
+            in place from pure Python. ``destroy()`` zeroes the client's mutable
+            ``bytearray`` seed copy in place and drops all references to immutable
+            key objects so they become eligible for garbage collection once the
+            caller also releases its references. Callers that want to minimize
+            long-lived plaintext ``str`` keys in memory should pass ``key`` as a
+            32-byte ``bytearray`` and zero their own buffer after ``create()``.
+        """
+        self._destroyed = True
+        if self._private_key_bytes:
+            self._private_key_bytes[:] = b"\x00" * len(self._private_key_bytes)
+        self._private_key_hex = ""
+        self._signing_key = None
+        self._session_cache = None
+        self._server_config = None
+        self._relayer_version_metadata = None
+        self._owner_address = None
+        self._pending_remember_keys.clear()
+        for attr in ("_session_build_task", "_owner_task"):
+            task = getattr(self, attr, None)
+            setattr(self, attr, None)
+            if task is not None and not task.done():
+                task.cancel()
+
+    async def close(self, clear_keys: bool = False) -> None:
+        """Close the underlying HTTP client and cancel any in-flight initialization tasks.
+
+        Args:
+            clear_keys: If ``True``, also call :meth:`destroy` to wipe internal
+                key buffers, drop signing credentials, and invalidate the client.
+        """
+        for attr in ("_session_build_task", "_owner_task"):
+            task = getattr(self, attr, None)
+            setattr(self, attr, None)
+            if task is not None and not task.done():
+                task.cancel()
+                try:
+                    await task
+                except (asyncio.CancelledError, Exception):
+                    # Ignore cancellation or transport errors from in-flight
+                    # session tasks during teardown.
+                    pass
+        if clear_keys:
+            self.destroy()
         if self._client is not None and not self._client.is_closed:
             await self._client.aclose()
             self._client = None
@@ -1443,7 +1514,11 @@ class MemWal:
         Returns:
             :class:`HealthResult` with status and version.
         """
+        if self._destroyed:
+            raise _destroyed_client_error()
         response = await self._http.get(f"{self._server_url}/health")
+        if self._destroyed:
+            raise _destroyed_client_error()
         if response.status_code != 200:
             raise MemWalError(f"Health check failed: {response.status_code}")
         data = response.json()
@@ -1462,7 +1537,8 @@ class MemWal:
 
     async def compatibility(self) -> Dict[str, Any]:
         """Fetch and validate the relayer compatibility contract."""
-
+        if self._destroyed:
+            raise _destroyed_client_error()
         return await self._ensure_compatible_relayer()
 
     # ============================================================
@@ -1545,6 +1621,8 @@ class MemWal:
         Returns:
             Public key hex string.
         """
+        if self._destroyed or self._signing_key is None:
+            raise _destroyed_client_error()
         return bytes_to_hex(bytes(self._signing_key.verify_key))
 
     # ============================================================
@@ -1552,6 +1630,8 @@ class MemWal:
     # ============================================================
 
     async def _ensure_compatible_relayer(self) -> Dict[str, Any]:
+        if self._destroyed:
+            raise _destroyed_client_error()
         if self._relayer_version_metadata is not None:
             return self._relayer_version_metadata
 
@@ -1559,14 +1639,20 @@ class MemWal:
             self._compatibility_lock = asyncio.Lock()
 
         async with self._compatibility_lock:
+            if self._destroyed:
+                raise _destroyed_client_error()
             if self._relayer_version_metadata is not None:
                 return self._relayer_version_metadata
 
             version_response = await self._http.get(f"{self._server_url}/version")
+            if self._destroyed:
+                raise _destroyed_client_error()
             if version_response.status_code == 200:
                 metadata = version_response.json()
             elif version_response.status_code in (404, 405):
                 health_response = await self._http.get(f"{self._server_url}/health")
+                if self._destroyed:
+                    raise _destroyed_client_error()
                 if health_response.status_code != 200:
                     raise MemWalError(
                         "Walrus Memory compatibility check failed: "
@@ -1684,10 +1770,16 @@ class MemWal:
             )
 
     async def _build_seal_session_inner(self) -> str:
+        if self._destroyed or self._signing_key is None:
+            raise _destroyed_client_error()
         cfg = await self._fetch_server_config()
+        if self._destroyed or self._signing_key is None:
+            raise _destroyed_client_error()
         await self._assert_first_package_version(
             cfg["network"], cfg["suiRpcUrl"], cfg["packageId"]
         )
+        if self._destroyed or self._signing_key is None:
+            raise _destroyed_client_error()
 
         session_signing_key = nacl.signing.SigningKey.generate()
         session_public_key = bytes(session_signing_key.verify_key)
@@ -1716,6 +1808,8 @@ class MemWal:
             separators=(",", ":"),
         )
         session_bytes = base64.b64encode(json_str.encode("utf-8")).decode("utf-8")
+        if self._destroyed:
+            raise _destroyed_client_error()
         self._session_cache = (
             session_bytes,
             int(time.time() * 1000) + SEAL_SESSION_TTL_MIN * 60_000 - SEAL_SESSION_SAFETY_MARGIN_MS,
@@ -1723,22 +1817,40 @@ class MemWal:
         return session_bytes
 
     async def _build_seal_session(self) -> str:
+        if self._destroyed:
+            raise _destroyed_client_error()
         now_ms = int(time.time() * 1000)
         if self._session_cache is not None:
             cached_bytes, expires_at_ms = self._session_cache
             if now_ms < expires_at_ms:
                 return cached_bytes
 
-        if self._session_build_task is not None:
-            return await self._session_build_task
+        task = self._session_build_task
+        if task is None or task.done():
+            task = asyncio.create_task(self._build_seal_session_inner())
+            self._session_build_task = task
+
+            def _on_session_build_done(done_task: "asyncio.Task[str]") -> None:
+                if self._session_build_task is done_task:
+                    self._session_build_task = None
+                if not done_task.cancelled():
+                    done_task.exception()
+
+            task.add_done_callback(_on_session_build_done)
 
-        self._session_build_task = asyncio.create_task(self._build_seal_session_inner())
         try:
-            return await self._session_build_task
-        finally:
-            self._session_build_task = None
+            result = await asyncio.shield(task)
+        except asyncio.CancelledError:
+            if self._destroyed:
+                raise _destroyed_client_error() from None
+            raise
+        if self._destroyed:
+            raise _destroyed_client_error()
+        return result
 
     async def _resolve_owner_inner(self) -> str:
+        if self._destroyed:
+            raise _destroyed_client_error()
         # POST /api/stats authenticates with the same delegate scheme and
         # returns the owner the relayer resolved from our key. Same approach
         # as the TypeScript SDK's resolveOwner().
@@ -1748,6 +1860,8 @@ class MemWal:
             {"namespace": self._namespace},
             include_seal_session=False,
         )
+        if self._destroyed:
+            raise _destroyed_client_error()
         owner = data.get("owner")
         if not owner:
             raise MemWalError(
@@ -1763,17 +1877,33 @@ class MemWal:
         The owner-scoped read routes take the address in the path, but the
         client is configured with only a delegate key and account id.
         """
+        if self._destroyed:
+            raise _destroyed_client_error()
         if self._owner_address is not None:
             return self._owner_address
 
-        if self._owner_task is not None:
-            return await self._owner_task
+        task = self._owner_task
+        if task is None or task.done():
+            task = asyncio.create_task(self._resolve_owner_inner())
+            self._owner_task = task
+
+            def _on_owner_done(done_task: "asyncio.Task[str]") -> None:
+                if self._owner_task is done_task:
+                    self._owner_task = None
+                if not done_task.cancelled():
+                    done_task.exception()
+
+            task.add_done_callback(_on_owner_done)
 
-        self._owner_task = asyncio.create_task(self._resolve_owner_inner())
         try:
-            return await self._owner_task
-        finally:
-            self._owner_task = None
+            result = await asyncio.shield(task)
+        except asyncio.CancelledError:
+            if self._destroyed:
+                raise _destroyed_client_error() from None
+            raise
+        if self._destroyed:
+            raise _destroyed_client_error()
+        return result
 
     async def _signed_request(
         self,
@@ -1803,8 +1933,12 @@ class MemWal:
             - ``x-account-id``: Walrus Memory account object ID
             - ``Content-Type``: application/json
         """
+        if self._destroyed or self._signing_key is None:
+            raise _destroyed_client_error()
 
         await self._ensure_compatible_relayer()
+        if self._destroyed or self._signing_key is None:
+            raise _destroyed_client_error()
 
         method_upper = method.upper()
         timestamp = str(int(time.time()))
@@ -1838,6 +1972,8 @@ class MemWal:
         }
         if include_seal_session:
             headers["x-seal-session"] = await self._build_seal_session()
+            if self._destroyed or self._signing_key is None:
+                raise _destroyed_client_error()
 
         response = await self._http.request(
             method=method_upper,
@@ -1846,6 +1982,8 @@ class MemWal:
             content=None if method_upper == "GET" else body_str,
             timeout=timeout,
         )
+        if self._destroyed or self._signing_key is None:
+            raise _destroyed_client_error()
 
         if response.status_code not in accepted_statuses:
             err_text = response.text
@@ -2073,7 +2211,7 @@ class MemWalSync:
     @classmethod
     def create(
         cls,
-        key: str,
+        key: Union[str, bytes, bytearray],
         account_id: str,
         server_url: Optional[str] = None,
         namespace: str = "default",
@@ -2278,9 +2416,18 @@ class MemWalSync:
         """Synchronous version of :meth:`MemWal.get_public_key_hex`."""
         return self._run(self._inner.get_public_key_hex())
 
-    def close(self) -> None:
-        """Close the underlying HTTP client."""
-        self._run(self._inner.close())
+    def destroy(self) -> None:
+        """Synchronous version of :meth:`MemWal.destroy`."""
+        self._inner.destroy()
+
+    def close(self, clear_keys: bool = False) -> None:
+        """Close the underlying HTTP client.
+
+        Args:
+            clear_keys: If ``True``, also call :meth:`destroy` to wipe internal
+                key buffers, drop signing credentials, and invalidate the client.
+        """
+        self._run(self._inner.close(clear_keys=clear_keys))
 
     def __enter__(self) -> "MemWalSync":
         return self

{memwal-0.2.1 → memwal-0.2.2.dev0}/memwal/mock.py

@@ -129,9 +129,13 @@ class MemWalMock:
     ) -> "MemWalMock":
         return cls(namespace, owner, initial_memories)
 
-    async def close(self) -> None:
+    def destroy(self) -> None:
         """No-op for API parity with :class:`MemWal`."""
 
+    async def close(self, clear_keys: bool = False) -> None:
+        """No-op for API parity with :class:`MemWal`."""
+        del clear_keys
+
     async def __aenter__(self) -> "MemWalMock":
         return self
 
@@ -714,8 +718,11 @@ class MemWalMockSync:
     def clear(self, namespace: Optional[str] = None) -> int:
         return self._inner.clear(namespace)
 
-    def close(self) -> None:
-        self._run(self._inner.close())
+    def destroy(self) -> None:
+        self._inner.destroy()
+
+    def close(self, clear_keys: bool = False) -> None:
+        self._run(self._inner.close(clear_keys=clear_keys))
 
     def __enter__(self) -> "MemWalMockSync":
         return self

{memwal-0.2.1 → memwal-0.2.2.dev0}/memwal/types.py

@@ -9,7 +9,7 @@ the Walrus Memory Rust server (TEE).
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Union
 
 # ============================================================
 # Config
@@ -34,8 +34,11 @@ class MemWalConfig:
     """Configuration for creating a Walrus Memory client.
 
     Attributes:
-        key: Ed25519 private key (hex string). This is the delegate key from the
-            Walrus Memory dashboard.
+        key: Ed25519 private key (hex string, ``suiprivkey1...``, or 32-byte
+            ``bytes`` / ``bytearray``). This is the delegate key from the
+            Walrus Memory dashboard. When passed as ``bytearray``, the client
+            copies the bytes into its own internal buffer so :meth:`MemWal.destroy`
+            zeroes only the client's copy.
         account_id: Walrus Memory account object ID on Sui.
         server_url: Server URL. ``None`` means omitted. Any explicit URL,
             including the hosted default, wins over ``env``.
@@ -46,7 +49,7 @@ class MemWalConfig:
             > ``DEFAULT_SERVER_URL``.
     """
 
-    key: str
+    key: Union[str, bytes, bytearray]
     account_id: str
     server_url: Optional[str] = None
     namespace: str = "default"

{memwal-0.2.1 → memwal-0.2.2.dev0}/memwal/utils.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 import base64
 import hashlib
 from datetime import datetime, timezone
-from typing import Tuple
+from typing import Tuple, Union
 
 import nacl.signing
 
@@ -51,7 +51,7 @@ def hex_to_bytes(hex_str: str) -> bytes:
     return bytes.fromhex(clean)
 
 
-def bytes_to_hex(b: bytes) -> str:
+def bytes_to_hex(b: Union[bytes, bytearray]) -> str:
     """Convert bytes to a lowercase hex string (no ``0x`` prefix).
 
     Args:
@@ -75,11 +75,14 @@ def sha256_hex(data: str) -> str:
     return hashlib.sha256(data.encode("utf-8")).hexdigest()
 
 
-def build_signing_key(private_key_hex: str) -> nacl.signing.SigningKey:
-    """Build a PyNaCl ``SigningKey`` from an Ed25519 private key hex string.
+def build_signing_key(
+    private_key: Union[str, bytes, bytearray]
+) -> nacl.signing.SigningKey:
+    """Build a PyNaCl ``SigningKey`` from an Ed25519 private key hex string or 32-byte buffer.
 
     Args:
-        private_key_hex: 32-byte Ed25519 seed as hex (64 hex chars), optionally ``0x``-prefixed.
+        private_key: 32-byte Ed25519 seed as hex (64 hex chars, optionally ``0x``-prefixed)
+            or raw 32-byte ``bytes`` / ``bytearray``.
 
     Returns:
         A ``nacl.signing.SigningKey`` instance.
@@ -87,7 +90,10 @@ def build_signing_key(private_key_hex: str) -> nacl.signing.SigningKey:
     Raises:
         ValueError: If the decoded seed is not exactly 32 bytes.
     """
-    seed_bytes = hex_to_bytes(private_key_hex)
+    if isinstance(private_key, (bytes, bytearray)):
+        seed_bytes = bytes(private_key)
+    else:
+        seed_bytes = hex_to_bytes(private_key)
     if len(seed_bytes) != 32:
         raise ValueError(
             f"Ed25519 seed must be exactly 32 bytes, got {len(seed_bytes)}"
@@ -290,12 +296,19 @@ def decode_sui_private_key(encoded: str) -> bytes:
     return seed
 
 
-def normalize_private_key(key: str) -> str:
-    """Accept either a hex seed or a Sui ``suiprivkey1...`` string, return hex.
+def normalize_private_key(key: Union[str, bytes, bytearray]) -> str:
+    """Accept a hex seed, ``suiprivkey1...`` string, or 32-byte ``bytes``/``bytearray``; return hex.
 
-    The TypeScript SDK takes both, and the dashboard hands out the bech32 form,
-    so hex-only input would reject a key a user reasonably expects to work.
+    The TypeScript SDK accepts hex, ``suiprivkey1...``, and 32-byte ``Uint8Array``.
     """
+    if isinstance(key, (bytes, bytearray)):
+        if len(key) != 32:
+            raise ValueError(f"Ed25519 seed must be exactly 32 bytes, got {len(key)}")
+        return bytes_to_hex(key)
+    if not isinstance(key, str):
+        raise TypeError(
+            f"key must be str, bytes, or bytearray, got {type(key).__name__}"
+        )
     candidate = key.strip()
     if candidate.lower().startswith("suiprivkey1"):
         return bytes_to_hex(decode_sui_private_key(candidate))

{memwal-0.2.1 → memwal-0.2.2.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "memwal"
-version = "0.2.1"
+version = "0.2.2.dev0"
 description = "Python SDK for Walrus Memory — Privacy-first AI memory with Ed25519 signing"
 readme = "README.md"
 license = "MIT"

memwal-0.2.2.dev0/tests/test_destroy_and_cancel_shield.py

@@ -0,0 +1,661 @@
+"""Tests for MemWal.destroy() key-wipe (GH #975) and concurrent
+initialization cancellation shielding (GH #1029)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Dict, List
+
+import httpx
+import pytest
+
+from memwal import (
+    MemWal,
+    MemWalError,
+    MemWalMock,
+    MemWalMockSync,
+    MemWalSync,
+    RecallParams,
+)
+
+PRIVATE_KEY_HEX = "a" * 64
+ACCOUNT_ID = "0x" + "1" * 64
+PACKAGE_ID = "0x" + "2" * 64
+SERVER_URL = "https://relayer.example.com"
+
+
+# ============================================================
+# GH #975: destroy(), close(clear_keys=True), bytes/bytearray keys
+# ============================================================
+
+
+class TestDestroyAndKeyWipe:
+    @pytest.mark.asyncio
+    async def test_accepts_bytes_and_bytearray_keys_and_clones_caller_buffer(self):
+        seed_bytes = bytes.fromhex(PRIVATE_KEY_HEX)
+        caller_buf = bytearray(seed_bytes)
+
+        from_hex = MemWal.create(
+            key=PRIVATE_KEY_HEX,
+            account_id=ACCOUNT_ID,
+            server_url=SERVER_URL,
+        )
+        from_bytes = MemWal.create(
+            key=seed_bytes,
+            account_id=ACCOUNT_ID,
+            server_url=SERVER_URL,
+        )
+        from_bytearray = MemWal.create(
+            key=caller_buf,
+            account_id=ACCOUNT_ID,
+            server_url=SERVER_URL,
+        )
+
+        expected_pub = await from_hex.get_public_key_hex()
+        assert await from_bytes.get_public_key_hex() == expected_pub
+        assert await from_bytearray.get_public_key_hex() == expected_pub
+
+        # Mutating caller's bytearray after create() does not affect client
+        caller_buf[:] = b"\xff" * 32
+        assert from_bytearray._private_key_bytes == bytearray(seed_bytes)
+        assert await from_bytearray.get_public_key_hex() == expected_pub
+
+        await from_hex.close()
+        await from_bytes.close()
+        await from_bytearray.close()
+
+    def test_rejects_wrong_length_bytes_key(self):
+        with pytest.raises(ValueError, match="32 bytes"):
+            MemWal.create(
+                key=b"\xaa" * 16,
+                account_id=ACCOUNT_ID,
+                server_url=SERVER_URL,
+            )
+
+    @pytest.mark.asyncio
+    async def test_destroy_zeroes_internal_buffer_without_mutating_caller_bytearray(self):
+        caller_buf = bytearray(bytes.fromhex(PRIVATE_KEY_HEX))
+        client = MemWal.create(
+            key=caller_buf,
+            account_id=ACCOUNT_ID,
+            server_url=SERVER_URL,
+        )
+        internal_ref = client._private_key_bytes
+        assert internal_ref == bytearray(bytes.fromhex(PRIVATE_KEY_HEX))
+
+        client.destroy()
+        # Idempotent second call
+        client.destroy()
+
+        # Internal bytearray was zeroed in place
+        assert internal_ref == bytearray(32)
+        assert all(b == 0 for b in client._private_key_bytes)
+        # Caller's bytearray was NOT mutated
+        assert caller_buf == bytearray(bytes.fromhex(PRIVATE_KEY_HEX))
+        # Credentials and caches dropped
+        assert client._private_key_hex == ""
+        assert client._signing_key is None
+        assert client._session_cache is None
+
+        with pytest.raises(MemWalError, match="Walrus Memory client was destroyed"):
+            await client.get_public_key_hex()
+        with pytest.raises(MemWalError, match="Walrus Memory client was destroyed"):
+            await client.remember("secret")
+        with pytest.raises(MemWalError, match="Walrus Memory client was destroyed"):
+            await client.recall("secret")
+        with pytest.raises(MemWalError, match="Walrus Memory client was destroyed"):
+            await client.health()
+        with pytest.raises(MemWalError, match="Walrus Memory client was destroyed"):
+            await client.compatibility()
+        with pytest.raises(MemWalError, match="Walrus Memory client was destroyed"):
+            await client.restore("default")
+
+        await client.close()
+
+    @pytest.mark.asyncio
+    async def test_destroy_mid_flight_aborts_pending_request(self):
+        config_entered = asyncio.Event()
+        release_config = asyncio.Event()
+
+        async def handler(request: httpx.Request) -> httpx.Response:
+            path = request.url.path
+            if path == "/version":
+                return httpx.Response(
+                    200,
+                    json={
+                        "apiVersion": "1.0.0",
+                        "relayerVersion": "0.1.0",
+                        "minSupportedSdk": {
+                            "typescript": "0.0.0",
+                            "python": "0.0.0",
+                            "mcp": "0.0.0",
+                        },
+                    },
+                )
+            if path == "/config":
+                config_entered.set()
+                await release_config.wait()
+                return httpx.Response(
+                    200,
+                    json={
+                        "packageId": PACKAGE_ID,
+                        "network": "testnet",
+                        "suiRpcUrl": "https://rpc.testnet.sui.io",
+                    },
+                )
+            return httpx.Response(500, text=f"unexpected {path}")
+
+        client = MemWal.create(
+            key=PRIVATE_KEY_HEX,
+            account_id=ACCOUNT_ID,
+            server_url=SERVER_URL,
+        )
+        client._client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+
+        recall_task = asyncio.create_task(client.recall(RecallParams(query="test")))
+        await config_entered.wait()
+
+        client.destroy()
+        release_config.set()
+
+        with pytest.raises(MemWalError, match="Walrus Memory client was destroyed"):
+            _ = await recall_task
+        assert client._session_cache is None
+        await client.close()
+
+    @pytest.mark.asyncio
+    async def test_destroy_while_signed_request_and_health_in_flight_rejects_response(self):
+        recall_entered = asyncio.Event()
+        release_recall = asyncio.Event()
+        health_entered = asyncio.Event()
+        release_health = asyncio.Event()
+
+        async def handler(request: httpx.Request) -> httpx.Response:
+            path = request.url.path
+            if path == "/version":
+                return httpx.Response(
+                    200,
+                    json={
+                        "apiVersion": "1.0.0",
+                        "relayerVersion": "0.1.0",
+                        "minSupportedSdk": {
+                            "typescript": "0.0.0",
+                            "python": "0.0.0",
+                            "mcp": "0.0.0",
+                        },
+                    },
+                )
+            if path == "/config":
+                return httpx.Response(
+                    200,
+                    json={
+                        "packageId": PACKAGE_ID,
+                        "network": "testnet",
+                        "suiRpcUrl": "https://rpc.testnet.sui.io",
+                    },
+                )
+            if request.url.host == "graphql.testnet.sui.io":
+                return httpx.Response(200, json={"data": {"object": {"version": 1}}})
+            if path == "/api/recall":
+                recall_entered.set()
+                await release_recall.wait()
+                return httpx.Response(
+                    200,
+                    json={
+                        "results": [
+                            {
+                                "id": "mem-1",
+                                "blob_id": "blob-1",
+                                "text": "match",
+                                "distance": 0.1,
+                                "namespace": "default",
+                            }
+                        ],
+                        "total": 1,
+                    },
+                )
+            if path == "/health":
+                health_entered.set()
+                await release_health.wait()
+                return httpx.Response(
+                    200,
+                    json={"status": "ok", "version": "0.1.0"},
+                )
+            return httpx.Response(500, text=f"unexpected {path}")
+
+        client = MemWal.create(
+            key=PRIVATE_KEY_HEX,
+            account_id=ACCOUNT_ID,
+            server_url=SERVER_URL,
+        )
+        client._client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+
+        recall_task = asyncio.create_task(client.recall(RecallParams(query="test")))
+        health_task = asyncio.create_task(client.health())
+        await recall_entered.wait()
+        await health_entered.wait()
+
+        client.destroy()
+        release_recall.set()
+        release_health.set()
+
+        with pytest.raises(MemWalError, match="Walrus Memory client was destroyed"):
+            _ = await recall_task
+        with pytest.raises(MemWalError, match="Walrus Memory client was destroyed"):
+            _ = await health_task
+        await client.close()
+
+    @pytest.mark.asyncio
+    async def test_close_with_clear_keys_destroys_client(self):
+        client = MemWal.create(
+            key=PRIVATE_KEY_HEX,
+            account_id=ACCOUNT_ID,
+            server_url=SERVER_URL,
+        )
+        # Default close(clear_keys=False) preserves keys
+        await client.close()
+        assert client._destroyed is False
+        assert await client.get_public_key_hex() != ""
+
+        # close(clear_keys=True) wipes keys and marks destroyed
+        await client.close(clear_keys=True)
+        assert client._destroyed is True
+        assert all(b == 0 for b in client._private_key_bytes)
+        with pytest.raises(MemWalError, match="Walrus Memory client was destroyed"):
+            await client.get_public_key_hex()
+
+    def test_sync_client_destroy_and_close_clear_keys(self):
+        caller_buf = bytearray(bytes.fromhex(PRIVATE_KEY_HEX))
+        sync_client = MemWalSync.create(
+            key=caller_buf,
+            account_id=ACCOUNT_ID,
+            server_url=SERVER_URL,
+        )
+        assert sync_client.get_public_key_hex() != ""
+
+        sync_client.close(clear_keys=True)
+        assert caller_buf == bytearray(bytes.fromhex(PRIVATE_KEY_HEX))
+        with pytest.raises(MemWalError, match="Walrus Memory client was destroyed"):
+            sync_client.get_public_key_hex()
+
+    @pytest.mark.asyncio
+    async def test_mock_parity_destroy_and_close_clear_keys(self):
+        mock = MemWalMock.create()
+        mock.destroy()
+        await mock.close(clear_keys=True)
+
+        sync_mock = MemWalMockSync.create()
+        sync_mock.destroy()
+        sync_mock.close(clear_keys=True)
+
+
+# ============================================================
+# GH #1029: Concurrent initialization cancellation shielding
+# ============================================================
+
+
+class Gate:
+    """Deterministic barrier when N coroutines enter, plus explicit release."""
+
+    def __init__(self, parties: int = 1) -> None:
+        self._parties = parties
+        self._count = 0
+        self.entered = asyncio.Event()
+        self.release_event = asyncio.Event()
+
+    async def wait(self) -> None:
+        self._count += 1
+        if self._count >= self._parties:
+            self.entered.set()
+        await self.release_event.wait()
+
+    def release(self) -> None:
+        self.release_event.set()
+
+
+class FakeTransport:
+    """Counted transport for /version, /config, GraphQL package version, and /api/recall."""
+
+    def __init__(
+        self,
+        *,
+        config_gate: Gate | None = None,
+        fail_config_times: int = 0,
+    ) -> None:
+        self.config_gate = config_gate
+        self.fail_config_times = fail_config_times
+        self.counts: Dict[str, int] = {
+            "version": 0,
+            "config": 0,
+            "graphql": 0,
+            "recall": 0,
+            "stats": 0,
+            "restore": 0,
+        }
+        self.recall_headers: List[Dict[str, str]] = []
+
+    async def handle(self, request: httpx.Request) -> httpx.Response:
+        path = request.url.path
+        if path == "/version":
+            self.counts["version"] += 1
+            return httpx.Response(
+                200,
+                json={
+                    "apiVersion": "1.0.0",
+                    "relayerVersion": "0.1.0",
+                    "minSupportedSdk": {
+                        "typescript": "0.0.0",
+                        "python": "0.0.0",
+                        "mcp": "0.0.0",
+                    },
+                },
+            )
+
+        if path == "/config":
+            self.counts["config"] += 1
+            if self.config_gate is not None:
+                await self.config_gate.wait()
+            if self.counts["config"] <= self.fail_config_times:
+                return httpx.Response(503, text="config temporary failure")
+            return httpx.Response(
+                200,
+                json={
+                    "packageId": PACKAGE_ID,
+                    "network": "testnet",
+                    "suiRpcUrl": "https://rpc.testnet.sui.io:443",
+                },
+            )
+
+        if request.url.host == "graphql.testnet.sui.io":
+            self.counts["graphql"] += 1
+            return httpx.Response(200, json={"data": {"object": {"version": 1}}})
+
+        if path == "/api/recall":
+            self.counts["recall"] += 1
+            self.recall_headers.append(dict(request.headers))
+            payload = json.loads(request.content.decode("utf-8"))
+            return httpx.Response(
+                200,
+                json={
+                    "results": [
+                        {
+                            "id": f"mem-{self.counts['recall']}",
+                            "blob_id": f"blob-{self.counts['recall']}",
+                            "text": f"match for {payload['query']}",
+                            "distance": 0.1,
+                            "namespace": payload["namespace"],
+                        }
+                    ],
+                    "total": 1,
+                },
+            )
+
+        if path == "/api/stats":
+            self.counts["stats"] += 1
+            if self.config_gate is not None:
+                await self.config_gate.wait()
+            return httpx.Response(200, json={"owner": "0x" + "9" * 64})
+
+        if path.startswith("/v1/owners/") and path.endswith("/namespaces"):
+            self.counts["restore"] += 1
+            return httpx.Response(
+                200,
+                json={"namespaces": [], "has_more": False, "snapshot_version": 2},
+            )
+
+        return httpx.Response(500, text=f"unexpected request {request.method} {request.url}")
+
+
+def make_client(transport: FakeTransport) -> MemWal:
+    client = MemWal.create(
+        key=PRIVATE_KEY_HEX,
+        account_id=ACCOUNT_ID,
+        server_url=SERVER_URL,
+    )
+    client._client = httpx.AsyncClient(transport=httpx.MockTransport(transport.handle))
+    return client
+
+
+async def wait_until(predicate, *, turns: int = 20) -> None:
+    for _ in range(turns):
+        if predicate():
+            return
+        await asyncio.sleep(0)
+    assert predicate()
+
+
+@pytest.mark.asyncio
+async def test_normal_concurrent_and_cached_retry() -> None:
+    gate = Gate()
+    transport = FakeTransport(config_gate=gate)
+    client = make_client(transport)
+
+    first = asyncio.create_task(client.recall(RecallParams(query="first")))
+    await gate.entered.wait()
+
+    second = asyncio.create_task(client.recall(RecallParams(query="second")))
+    await wait_until(lambda: client._session_build_task is not None)
+    gate.release()
+
+    r1, r2 = await asyncio.gather(first, second)
+    r3 = await client.recall(RecallParams(query="third"))
+
+    assert [r1.total, r2.total, r3.total] == [1, 1, 1]
+    assert transport.counts == {
+        "version": 1,
+        "config": 1,
+        "graphql": 1,
+        "recall": 3,
+        "stats": 0,
+        "restore": 0,
+    }
+    sessions = {h["x-seal-session"] for h in transport.recall_headers}
+    assert len(sessions) == 1
+
+    await client.close()
+
+
+@pytest.mark.asyncio
+async def test_cancel_creator_preserves_waiter_and_late_join() -> None:
+    gate = Gate()
+    transport = FakeTransport(config_gate=gate)
+    client = make_client(transport)
+
+    creator = asyncio.create_task(client.recall(RecallParams(query="creator")))
+    await gate.entered.wait()
+
+    waiter = asyncio.create_task(client.recall(RecallParams(query="waiter")))
+    await asyncio.sleep(0)
+
+    creator.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        _ = await creator
+
+    # Join after creator cancelled while the shared session build is still in flight.
+    late = asyncio.create_task(client.recall(RecallParams(query="late")))
+    await asyncio.sleep(0)
+
+    gate.release()
+    waiter_result, late_result = await asyncio.gather(waiter, late)
+    retry_result = await client.recall(RecallParams(query="retry"))
+
+    assert waiter_result.results[0].text == "match for waiter"
+    assert late_result.results[0].text == "match for late"
+    assert retry_result.results[0].text == "match for retry"
+    assert transport.counts["config"] == 1
+    assert transport.counts["graphql"] == 1
+    assert transport.counts["recall"] == 3
+
+    await client.close()
+
+
+@pytest.mark.asyncio
+async def test_cancel_waiter_preserves_creator_and_late_join() -> None:
+    gate = Gate()
+    transport = FakeTransport(config_gate=gate)
+    client = make_client(transport)
+
+    creator = asyncio.create_task(client.recall(RecallParams(query="creator")))
+    await gate.entered.wait()
+
+    waiter = asyncio.create_task(client.recall(RecallParams(query="waiter")))
+    await asyncio.sleep(0)
+
+    waiter.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        _ = await waiter
+
+    late = asyncio.create_task(client.recall(RecallParams(query="late")))
+    await asyncio.sleep(0)
+
+    gate.release()
+    creator_result, late_result = await asyncio.gather(creator, late)
+    assert creator_result.results[0].text == "match for creator"
+    assert late_result.results[0].text == "match for late"
+    assert transport.counts["config"] == 1
+    assert transport.counts["graphql"] == 1
+    assert transport.counts["recall"] == 2
+
+    await client.close()
+
+
+@pytest.mark.asyncio
+async def test_real_initialization_failure_reaches_both_then_retry_succeeds() -> None:
+    gate = Gate()
+    transport = FakeTransport(config_gate=gate, fail_config_times=1)
+    client = make_client(transport)
+
+    first = asyncio.create_task(client.recall(RecallParams(query="first")))
+    await gate.entered.wait()
+
+    second = asyncio.create_task(client.recall(RecallParams(query="second")))
+    await asyncio.sleep(0)
+    gate.release()
+
+    outcomes = await asyncio.gather(first, second, return_exceptions=True)
+    assert all(isinstance(outcome, MemWalError) for outcome in outcomes)
+    assert transport.counts["config"] == 1
+    assert transport.counts["recall"] == 0
+    assert client._session_build_task is None
+
+    recovered = await client.recall(RecallParams(query="recovered"))
+    assert recovered.results[0].text == "match for recovered"
+    assert transport.counts["config"] == 2
+    assert transport.counts["graphql"] == 1
+    assert transport.counts["recall"] == 1
+
+    await client.close()
+
+
+@pytest.mark.asyncio
+async def test_all_cancelled_success_populates_cache() -> None:
+    gate = Gate()
+    transport = FakeTransport(config_gate=gate)
+    client = make_client(transport)
+
+    first = asyncio.create_task(client.recall(RecallParams(query="first")))
+    await gate.entered.wait()
+    second = asyncio.create_task(client.recall(RecallParams(query="second")))
+    await asyncio.sleep(0)
+
+    first.cancel()
+    second.cancel()
+    for task in (first, second):
+        with pytest.raises(asyncio.CancelledError):
+            _ = await task
+
+    gate.release()
+    await wait_until(lambda: client._session_build_task is None)
+
+    later = await client.recall(RecallParams(query="later"))
+    assert later.results[0].text == "match for later"
+    assert transport.counts["config"] == 1
+    assert transport.counts["graphql"] == 1
+    assert transport.counts["recall"] == 1
+
+    await client.close()
+
+
+@pytest.mark.asyncio
+async def test_all_cancelled_failure_has_no_unretrieved_exception() -> None:
+    loop = asyncio.get_running_loop()
+    unhandled: List[Dict[str, object]] = []
+    previous_handler = loop.get_exception_handler()
+
+    def handler(_loop: asyncio.AbstractEventLoop, context: Dict[str, object]) -> None:
+        unhandled.append(context)
+
+    loop.set_exception_handler(handler)
+    try:
+        gate = Gate()
+        transport = FakeTransport(config_gate=gate, fail_config_times=1)
+        client = make_client(transport)
+
+        first = asyncio.create_task(client.recall(RecallParams(query="first")))
+        await gate.entered.wait()
+        first.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            _ = await first
+
+        gate.release()
+        await wait_until(lambda: client._session_build_task is None)
+
+        later = await client.recall(RecallParams(query="later"))
+        assert later.results[0].text == "match for later"
+        assert transport.counts["config"] == 2
+        await client.close()
+    finally:
+        loop.set_exception_handler(previous_handler)
+
+    assert unhandled == []
+
+
+@pytest.mark.asyncio
+async def test_close_cancels_and_drains_orphaned_initialization() -> None:
+    gate = Gate()
+    transport = FakeTransport(config_gate=gate)
+    client = make_client(transport)
+
+    first = asyncio.create_task(client.recall(RecallParams(query="first")))
+    await gate.entered.wait()
+    build_task = client._session_build_task
+    assert build_task is not None
+
+    first.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        _ = await first
+
+    await client.close()
+    assert build_task.cancelled()
+    assert client._session_build_task is None
+    assert client._session_cache is None
+
+
+@pytest.mark.asyncio
+async def test_cancel_owner_resolution_creator_preserves_waiter() -> None:
+    gate = Gate()
+    transport = FakeTransport(config_gate=gate)
+    client = make_client(transport)
+
+    creator = asyncio.create_task(client.list_namespaces())
+    await gate.entered.wait()
+
+    waiter = asyncio.create_task(client.list_namespaces())
+    await asyncio.sleep(0)
+
+    creator.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        _ = await creator
+
+    late = asyncio.create_task(client.list_namespaces())
+    await asyncio.sleep(0)
+
+    gate.release()
+    waiter_res, late_res = await asyncio.gather(waiter, late)
+    assert waiter_res.namespaces == []
+    assert late_res.namespaces == []
+    assert transport.counts["stats"] == 1
+    assert transport.counts["restore"] == 2
+
+    await client.close()