memwal 0.1.7.dev0__tar.gz → 0.1.7.dev2__tar.gz

{memwal-0.1.7.dev0 → memwal-0.1.7.dev2}/CHANGELOG.md

@@ -1,5 +1,11 @@
 # memwal
 
+## Unreleased
+
+### Added
+
+- Added `MemWalClockDriftError`, raised when the relayer rejects a request because the signed timestamp is outside its accepted clock-drift window (`401` + `x-auth-error: ERR_TIMESTAMP_OUT_OF_BOUNDS`). Surfaces an actionable "synchronize the client clock" message instead of an opaque `401`. Subclasses `MemWalError`, so existing `except MemWalError` handlers still catch it.
+
 ## 0.1.7
 
 ### Added

{memwal-0.1.7.dev0 → memwal-0.1.7.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memwal
-Version: 0.1.7.dev0
+Version: 0.1.7.dev2
 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

{memwal-0.1.7.dev0 → memwal-0.1.7.dev2}/memwal/__init__.py

@@ -24,6 +24,7 @@ Quick start::
 
 from .client import (
     MemWal,
+    MemWalClockDriftError,
     MemWalCompatibilityError,
     MemWalError,
     MemWalRememberJobFailed,
@@ -78,6 +79,7 @@ __all__ = [
     "MemWalMockSeed",
     "MemWalError",
     "MemWalCompatibilityError",
+    "MemWalClockDriftError",
     "MemWalRememberJobFailed",
     "MemWalRememberJobNotFound",
     "MemWalRememberJobTimeout",
@@ -120,4 +122,4 @@ __all__ = [
     "RecallManualResult",
 ]
 
-__version__ = "0.1.7.dev0"
+__version__ = "0.1.7.dev2"

{memwal-0.1.7.dev0 → memwal-0.1.7.dev2}/memwal/client.py

@@ -73,6 +73,7 @@ from .utils import (
     bytes_to_hex,
     delegate_key_to_sui_address,
     encode_sui_private_key,
+    normalize_private_key,
     sha256_hex,
     sign_message,
     sign_sui_personal_message,
@@ -213,8 +214,8 @@ class MemWal:
     """
 
     def __init__(self, config: MemWalConfig) -> None:
-        self._signing_key = build_signing_key(config.key)
-        self._private_key_hex = config.key if not config.key.startswith("0x") else config.key[2:]
+        self._private_key_hex = normalize_private_key(config.key)
+        self._signing_key = build_signing_key(self._private_key_hex)
         self._account_id = config.account_id
         self._server_url = config.server_url.rstrip("/")
         self._namespace = config.namespace
@@ -1189,6 +1190,16 @@ class MemWal:
                     f"(HTTP 426 Upgrade Required). Relayer response: "
                     f"{err_text[:300] or 'upgrade required'}"
                 )
+            # A stale/future-dated signature is rejected with 401 + a machine-
+            # readable reason header. Surface it as an actionable clock-drift
+            # error rather than an opaque 401 so the caller can fix node time.
+            if response.headers.get("x-auth-error") == "ERR_TIMESTAMP_OUT_OF_BOUNDS":
+                raise MemWalClockDriftError(
+                    "Request rejected: signed timestamp is outside the relayer's "
+                    "accepted clock-drift window. Synchronize this client's clock "
+                    "(NTP); if the deployment needs a wider tolerance, raise "
+                    "AUTH_MAX_CLOCK_DRIFT_SECS on the relayer."
+                )
             raise _HttpStatusError(
                 status=response.status_code,
                 body=err_text,
@@ -1209,6 +1220,15 @@ class MemWalCompatibilityError(MemWalError):
     pass
 
 
+class MemWalClockDriftError(MemWalError):
+    """Raised when the relayer rejects a request because the signed timestamp is
+    outside its accepted clock-drift window (401 + ``x-auth-error:
+    ERR_TIMESTAMP_OUT_OF_BOUNDS``). Indicates the client's clock is skewed
+    relative to the relayer; sync via NTP or widen the relayer's window."""
+
+    pass
+
+
 class _HttpStatusError(MemWalError):
     """Internal: raised when an HTTP response status is not in ``accepted_statuses``.
 

{memwal-0.1.7.dev0 → memwal-0.1.7.dev2}/memwal/utils.py

@@ -232,6 +232,58 @@ def bech32_encode(hrp: str, data: bytes) -> str:
     return hrp + "1" + "".join(_BECH32_CHARSET[d] for d in combined)
 
 
+def bech32_decode(bech: str) -> Tuple[str, bytes]:
+    """Decode a bech32 string into its human-readable part and 5-bit data."""
+    if bech != bech.lower() and bech != bech.upper():
+        raise ValueError("bech32 string is mixed case")
+    bech = bech.lower()
+    pos = bech.rfind("1")
+    if pos < 1 or pos + 7 > len(bech):
+        raise ValueError("bech32 string has no valid separator")
+
+    hrp = bech[:pos]
+    try:
+        data = bytes(_BECH32_CHARSET.index(c) for c in bech[pos + 1 :])
+    except ValueError as exc:
+        raise ValueError("bech32 string has a character outside the charset") from exc
+
+    if _bech32_polymod(_bech32_hrp_expand(hrp) + data) != 1:
+        raise ValueError("bech32 checksum mismatch")
+    return hrp, data[:-6]
+
+
+def decode_sui_private_key(encoded: str) -> bytes:
+    """Decode a Sui bech32 ``suiprivkey1...`` string to its 32-byte Ed25519 seed.
+
+    Inverse of :func:`encode_sui_private_key`. Mirrors ``decodeSuiPrivateKey``
+    from ``@mysten/sui``, which the TypeScript SDK uses.
+    """
+    hrp, data = bech32_decode(encoded)
+    if hrp != "suiprivkey":
+        raise ValueError(f"expected a suiprivkey string, got prefix {hrp!r}")
+
+    payload = _convertbits(data, 5, 8, pad=False)
+    if not payload or payload[0] != _SUI_ED25519_SCHEME_FLAG:
+        raise ValueError("only Ed25519 private keys are supported")
+
+    seed = payload[1:]
+    if len(seed) != 32:
+        raise ValueError(f"Ed25519 seed must be exactly 32 bytes, got {len(seed)}")
+    return seed
+
+
+def normalize_private_key(key: str) -> str:
+    """Accept either a hex seed or a Sui ``suiprivkey1...`` string, 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.
+    """
+    candidate = key.strip()
+    if candidate.lower().startswith("suiprivkey1"):
+        return bytes_to_hex(decode_sui_private_key(candidate))
+    return candidate[2:] if candidate.startswith("0x") else candidate
+
+
 def encode_sui_private_key(seed_bytes: bytes) -> str:
     """Encode a 32-byte Ed25519 seed to Sui bech32 `suiprivkey...` format."""
     if len(seed_bytes) != 32:

{memwal-0.1.7.dev0 → memwal-0.1.7.dev2}/pyproject.toml

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

{memwal-0.1.7.dev0 → memwal-0.1.7.dev2}/tests/test_client.py

@@ -17,7 +17,13 @@ import nacl.signing
 import pytest
 import respx
 
-from memwal.client import MemWal, MemWalCompatibilityError, MemWalError, MemWalSync
+from memwal.client import (
+    MemWal,
+    MemWalClockDriftError,
+    MemWalCompatibilityError,
+    MemWalError,
+    MemWalSync,
+)
 from memwal.types import (
     RecallManualOptions,
     RecallParams,
@@ -468,6 +474,24 @@ class TestErrorHandling:
         ):
             await memwal_client.recall("test")
 
+    @respx.mock
+    async def test_clock_drift_header_raises_clock_drift_error(
+        self, memwal_client: MemWal
+    ) -> None:
+        """A 401 carrying x-auth-error: ERR_TIMESTAMP_OUT_OF_BOUNDS should surface
+        as an actionable MemWalClockDriftError, not an opaque HTTP error."""
+        mock_seal_session_prereqs()
+        respx.post(f"{_TEST_SERVER}/api/remember").mock(
+            return_value=httpx.Response(
+                401,
+                headers={"x-auth-error": "ERR_TIMESTAMP_OUT_OF_BOUNDS"},
+                text="",
+            )
+        )
+
+        with pytest.raises(MemWalClockDriftError, match="clock-drift window"):
+            await memwal_client.remember("test")
+
     @respx.mock
     async def test_500_raises_memwal_error(self, memwal_client: MemWal) -> None:
         """Server errors should raise MemWalError."""

{memwal-0.1.7.dev0 → memwal-0.1.7.dev2}/tests/test_integration.py

@@ -58,6 +58,18 @@ SERVER_URL = os.environ.get("MEMWAL_SERVER_URL", "https://relayer-staging.memory
 PRIVATE_KEY_HEX = os.environ.get("MEMWAL_PRIVATE_KEY", "")
 ACCOUNT_ID = os.environ.get("MEMWAL_ACCOUNT_ID", "")
 
+# A live write runs embed -> SEAL encrypt -> Walrus upload -> on-chain metadata.
+# Measured around 44s against the dev relayer, so the SDK's 60s default leaves
+# too little headroom to be reliable in CI. 120s matches what the SDK already
+# uses for bulk pipelines.
+_REMEMBER_TIMEOUT_MS = int(os.environ.get("MEMWAL_REMEMBER_TIMEOUT_MS", "120000"))
+
+# Every authenticated test writes into a namespace unique to this run. The bench
+# account is shared, and `default` in particular is what real users get, so a
+# recurring job must not leave live Walrus blobs there.
+_E2E_NAMESPACE = f"sdk-e2e-{uuid.uuid4().hex[:8]}"
+_E2E_NAMESPACE_ALT = f"{_E2E_NAMESPACE}-alt"
+
 HAS_KEY = bool(PRIVATE_KEY_HEX and ACCOUNT_ID)
 
 requires_key = pytest.mark.skipif(
@@ -65,6 +77,24 @@ requires_key = pytest.mark.skipif(
     reason="MEMWAL_PRIVATE_KEY and MEMWAL_ACCOUNT_ID not set",
 )
 
+
+def _sync_client(namespace: str = _E2E_NAMESPACE) -> MemWalSync:
+    return MemWalSync.create(
+        key=PRIVATE_KEY_HEX,
+        account_id=ACCOUNT_ID,
+        server_url=SERVER_URL,
+        namespace=namespace,
+    )
+
+
+def _async_client(namespace: str = _E2E_NAMESPACE) -> MemWal:
+    return MemWal.create(
+        key=PRIVATE_KEY_HEX,
+        account_id=ACCOUNT_ID,
+        server_url=SERVER_URL,
+        namespace=namespace,
+    )
+
 # ── Helpers ───────────────────────────────────────────────────────────────────
 
 
@@ -189,37 +219,42 @@ class TestRemember:
     """remember() / remember_and_wait() against live server."""
 
     def test_remember_returns_job_id_and_status(self) -> None:
-        mw = MemWalSync.create(
-            key=PRIVATE_KEY_HEX, account_id=ACCOUNT_ID, server_url=SERVER_URL
-        )
-        result = mw.remember("Integration test: the sky is blue", namespace="sdk-test")
+        mw = _sync_client()
+        result = mw.remember("Integration test: the sky is blue")
         assert result.job_id is not None and isinstance(result.job_id, str)
         assert result.status in ("pending", "running")
         print(f"\n  accepted job={result.job_id[:8]}... status={result.status}")
 
     def test_remember_and_wait_returns_blob_and_owner(self) -> None:
-        mw = MemWalSync.create(
-            key=PRIVATE_KEY_HEX, account_id=ACCOUNT_ID, server_url=SERVER_URL
+        mw = _sync_client()
+        result = mw.remember_and_wait(
+            "Integration test: the sky is blue", timeout_ms=_REMEMBER_TIMEOUT_MS
         )
-        result = mw.remember_and_wait("Integration test: the sky is blue", namespace="sdk-test")
         assert result.id is not None and isinstance(result.id, str)
         assert result.blob_id is not None and isinstance(result.blob_id, str)
         assert result.owner.startswith("0x")
         print(f"\n  done job={result.id[:8]}... blob={result.blob_id[:8]}...")
 
-    def test_remember_default_namespace(self) -> None:
-        mw = MemWalSync.create(
-            key=PRIVATE_KEY_HEX, account_id=ACCOUNT_ID, server_url=SERVER_URL
+    def test_remember_uses_the_client_namespace(self) -> None:
+        """Omitting `namespace` falls back to the one the client was built with.
+
+        The literal `"default"` fallback is asserted in the mocked suite; proving
+        it here would mean writing a live blob into the namespace real users get.
+        """
+        mw = _sync_client()
+        result = mw.remember_and_wait(
+            "Integration test: namespace fallback", timeout_ms=_REMEMBER_TIMEOUT_MS
         )
-        result = mw.remember_and_wait("Integration test: namespace default")
-        assert result.namespace == "default"
+        assert result.namespace == _E2E_NAMESPACE
 
     def test_remember_custom_namespace(self) -> None:
-        mw = MemWalSync.create(
-            key=PRIVATE_KEY_HEX, account_id=ACCOUNT_ID, server_url=SERVER_URL
+        mw = _sync_client()
+        result = mw.remember_and_wait(
+            "Integration test: custom namespace",
+            namespace=_E2E_NAMESPACE_ALT,
+            timeout_ms=_REMEMBER_TIMEOUT_MS,
         )
-        result = mw.remember_and_wait("Integration test: custom namespace", namespace="sdk-test")
-        assert result.namespace == "sdk-test"
+        assert result.namespace == _E2E_NAMESPACE_ALT
 
 
 @requires_key
@@ -227,25 +262,19 @@ class TestRecall:
     """recall() against live server."""
 
     def test_recall_returns_list(self) -> None:
-        mw = MemWalSync.create(
-            key=PRIVATE_KEY_HEX, account_id=ACCOUNT_ID, server_url=SERVER_URL
-        )
+        mw = _sync_client()
         result = mw.recall("sky blue", limit=5)
         assert isinstance(result.results, list)
         assert result.total >= 0
         print(f"\n  recall total={result.total}")
 
     def test_recall_respects_limit(self) -> None:
-        mw = MemWalSync.create(
-            key=PRIVATE_KEY_HEX, account_id=ACCOUNT_ID, server_url=SERVER_URL
-        )
+        mw = _sync_client()
         result = mw.recall("test", limit=2)
         assert len(result.results) <= 2
 
     def test_recall_result_has_expected_fields(self) -> None:
-        mw = MemWalSync.create(
-            key=PRIVATE_KEY_HEX, account_id=ACCOUNT_ID, server_url=SERVER_URL
-        )
+        mw = _sync_client()
         result = mw.recall("test", limit=3)
         for mem in result.results:
             assert isinstance(mem.text, str)
@@ -258,13 +287,8 @@ class TestAnalyze:
     """analyze() against live server."""
 
     def test_analyze_returns_facts(self) -> None:
-        mw = MemWalSync.create(
-            key=PRIVATE_KEY_HEX, account_id=ACCOUNT_ID, server_url=SERVER_URL
-        )
-        result = mw.analyze(
-            "I love hiking and my favorite food is pho.",
-            namespace="sdk-test",
-        )
+        mw = _sync_client()
+        result = mw.analyze("I love hiking and my favorite food is pho.")
         assert isinstance(result.facts, list)
         assert result.total >= 0
         assert result.owner.startswith("0x")
@@ -278,9 +302,7 @@ class TestAsk:
     """ask() against live server."""
 
     def test_ask_returns_string_answer(self) -> None:
-        mw = MemWalSync.create(
-            key=PRIVATE_KEY_HEX, account_id=ACCOUNT_ID, server_url=SERVER_URL
-        )
+        mw = _sync_client()
         result = mw.ask("What outdoor activities do I enjoy?", limit=3)
         assert isinstance(result.answer, str)
         assert len(result.answer) > 0
@@ -301,12 +323,10 @@ class TestFullFlow:
         text = f"SDK e2e test {unique}: quantum entanglement in photonics"
         ns = f"sdk-e2e-{unique}"
 
-        mw = MemWalSync.create(
-            key=PRIVATE_KEY_HEX, account_id=ACCOUNT_ID, server_url=SERVER_URL
-        )
+        mw = _sync_client()
 
         # Store a distinctive memory in an isolated namespace
-        mem = mw.remember_and_wait(text, namespace=ns)
+        mem = mw.remember_and_wait(text, namespace=ns, timeout_ms=_REMEMBER_TIMEOUT_MS)
         assert mem.id is not None
 
         # Recall — should find the stored memory
@@ -320,11 +340,11 @@ class TestFullFlow:
 
     def test_remember_then_ask_uses_memory(self) -> None:
         """remember → ask — answer should reference the stored fact."""
-        mw = MemWalSync.create(
-            key=PRIVATE_KEY_HEX, account_id=ACCOUNT_ID, server_url=SERVER_URL
+        mw = _sync_client()
+        mw.remember_and_wait(
+            "I am allergic to shellfish", timeout_ms=_REMEMBER_TIMEOUT_MS
         )
-        mw.remember_and_wait("I am allergic to shellfish", namespace="sdk-test")
-        result = mw.ask("What are my food allergies?", limit=3, namespace="sdk-test")
+        result = mw.ask("What are my food allergies?", limit=3)
         assert isinstance(result.answer, str)
         assert len(result.answer) > 0
         print(f"\n  ask answer: {result.answer[:100]}")
@@ -338,38 +358,30 @@ class TestAsync:
     """Async client variants."""
 
     async def test_async_health(self) -> None:
-        async with MemWal.create(
-            key=PRIVATE_KEY_HEX, account_id=ACCOUNT_ID, server_url=SERVER_URL
-        ) as mw:
+        async with _async_client() as mw:
             result = await mw.health()
             assert result.status == "ok"
 
     async def test_async_remember(self) -> None:
-        async with MemWal.create(
-            key=PRIVATE_KEY_HEX, account_id=ACCOUNT_ID, server_url=SERVER_URL
-        ) as mw:
+        async with _async_client() as mw:
             result = await mw.remember("Async SDK test: Paris is the capital of France")
             assert result.job_id is not None
             assert result.status in ("pending", "running")
 
     async def test_async_recall(self) -> None:
-        async with MemWal.create(
-            key=PRIVATE_KEY_HEX, account_id=ACCOUNT_ID, server_url=SERVER_URL
-        ) as mw:
-            await mw.remember_and_wait("Async SDK test: I enjoy reading")
+        async with _async_client() as mw:
+            await mw.remember_and_wait(
+                "Async SDK test: I enjoy reading", timeout_ms=_REMEMBER_TIMEOUT_MS
+            )
             result = await mw.recall("reading books", limit=3)
             assert isinstance(result.results, list)
 
     async def test_async_analyze(self) -> None:
-        async with MemWal.create(
-            key=PRIVATE_KEY_HEX, account_id=ACCOUNT_ID, server_url=SERVER_URL
-        ) as mw:
-            result = await mw.analyze("I drink tea every morning.", namespace="sdk-test")
+        async with _async_client() as mw:
+            result = await mw.analyze("I drink tea every morning.")
             assert isinstance(result.facts, list)
 
     async def test_async_ask(self) -> None:
-        async with MemWal.create(
-            key=PRIVATE_KEY_HEX, account_id=ACCOUNT_ID, server_url=SERVER_URL
-        ) as mw:
+        async with _async_client() as mw:
             result = await mw.ask("What do I drink?", limit=3)
             assert isinstance(result.answer, str)

{memwal-0.1.7.dev0 → memwal-0.1.7.dev2}/tests/test_signing.py

@@ -12,6 +12,7 @@ import hashlib
 import json
 
 import nacl.signing
+import pytest
 
 from memwal.utils import (
     build_seal_session_personal_message,
@@ -144,7 +145,10 @@ class TestBuildSignatureMessage:
             nonce="550e8400-e29b-41d4-a716-446655440000",
             account_id="0xabc123",
         )
-        assert result == "1700000000.POST./api/remember.abc123.550e8400-e29b-41d4-a716-446655440000.0xabc123"
+        assert result == (
+            "1700000000.POST./api/remember.abc123"
+            ".550e8400-e29b-41d4-a716-446655440000.0xabc123"
+        )
 
     def test_get_method(self) -> None:
         result = build_signature_message(
@@ -175,7 +179,9 @@ class TestBuildSignatureMessage:
         nonce = "550e8400-e29b-41d4-a716-446655440000"
         account_id = "0xabc123"
 
-        message = build_signature_message(timestamp, method, path, body_hash, nonce=nonce, account_id=account_id)
+        message = build_signature_message(
+            timestamp, method, path, body_hash, nonce=nonce, account_id=account_id
+        )
         sig_hex, pub_hex = sign_message(message, signing_key)
 
         # Verify (as the server would)
@@ -239,9 +245,10 @@ class TestDelegateKeyUtils:
 
     def test_sui_address_matches_typescript_sdk(self):
         """Verify blake2b-256(0x00 || pubkey) matches TS delegateKeyToSuiAddress output."""
-        from memwal.utils import delegate_key_to_public_key, delegate_key_to_sui_address
         import hashlib
 
+        from memwal.utils import delegate_key_to_public_key, delegate_key_to_sui_address
+
         pub = delegate_key_to_public_key(self._KEY)
         scheme_input = bytes([0x00]) + pub
         expected = "0x" + hashlib.blake2b(scheme_input, digest_size=32).hexdigest()
@@ -272,3 +279,52 @@ class TestSealSessionUtils:
         raw = json.loads(json.dumps(signature))  # assert it's JSON-safe text
         assert isinstance(raw, str)
         assert len(base64.b64decode(signature)) == 97
+
+
+class TestPrivateKeyFormats:
+    """The dashboard hands out `suiprivkey1...`; the SDK must take both forms."""
+
+    _SEED_HEX = "17dc3c1eecfcdc014c0eba65c1f87897abbbd214fa32d4018f48669b5d37c413"
+
+    def test_decode_reverses_encode(self) -> None:
+        from memwal.utils import decode_sui_private_key, encode_sui_private_key
+
+        seed = bytes.fromhex(self._SEED_HEX)
+        assert decode_sui_private_key(encode_sui_private_key(seed)) == seed
+
+    def test_normalize_accepts_every_accepted_form(self) -> None:
+        from memwal.utils import encode_sui_private_key, normalize_private_key
+
+        seed = bytes.fromhex(self._SEED_HEX)
+        for form in (
+            self._SEED_HEX,
+            f"0x{self._SEED_HEX}",
+            encode_sui_private_key(seed),
+            f"  {encode_sui_private_key(seed)}  ",
+        ):
+            assert normalize_private_key(form) == self._SEED_HEX
+
+    def test_bech32_key_produces_the_same_client_identity(self) -> None:
+        from memwal.client import MemWal
+        from memwal.utils import encode_sui_private_key
+
+        bech32 = encode_sui_private_key(bytes.fromhex(self._SEED_HEX))
+        from_hex = MemWal.create(key=self._SEED_HEX, account_id="0xtest")
+        from_bech32 = MemWal.create(key=bech32, account_id="0xtest")
+        assert from_bech32._private_key_hex == from_hex._private_key_hex
+        assert bytes(from_bech32._signing_key) == bytes(from_hex._signing_key)
+
+    def test_rejects_a_non_ed25519_scheme(self) -> None:
+        from memwal.utils import _convertbits, bech32_encode, decode_sui_private_key
+
+        payload = bytes([1]) + bytes.fromhex(self._SEED_HEX)  # scheme flag 1 = secp256k1
+        with pytest.raises(ValueError, match="Ed25519"):
+            decode_sui_private_key(bech32_encode("suiprivkey", _convertbits(payload, 8, 5)))
+
+    def test_rejects_a_corrupted_checksum(self) -> None:
+        from memwal.utils import decode_sui_private_key, encode_sui_private_key
+
+        encoded = encode_sui_private_key(bytes.fromhex(self._SEED_HEX))
+        corrupted = encoded[:-1] + ("q" if encoded[-1] != "q" else "p")
+        with pytest.raises(ValueError, match="checksum"):
+            decode_sui_private_key(corrupted)