locivault-client 0.1.0__tar.gz

locivault_client-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: locivault-client
+Version: 0.1.0
+Summary: Python client for LocIVault — encrypted, agent-owned memory with x402 micropayments
+License: MIT
+Project-URL: Homepage, https://locivault.dev
+Project-URL: Repository, https://github.com/locivault/locivault-python
+Project-URL: Bug Tracker, https://github.com/locivault/locivault-python/issues
+Keywords: ai,agent,memory,encryption,x402,web3,locivault
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Requires-Dist: cryptography>=41
+Requires-Dist: eth-account>=0.10
+Provides-Extra: payments
+Requires-Dist: x402[evm]>=2.5; extra == "payments"
+Provides-Extra: all
+Requires-Dist: x402[evm]>=2.5; extra == "all"
+
+# locivault-client
+
+Python client SDK for [LocIVault](https://locivault.dev) — encrypted, agent-owned memory storage with x402 micropayments.
+
+## What it does
+
+AI agents need memory that persists across sessions and travels with them across platforms. LocIVault stores encrypted blobs identified by wallet address. The agent holds the key. The server never sees plaintext.
+
+- **Encrypted at rest** — AES-256-GCM, key derived from your wallet's private key
+- **x402 micropayments** — first 50 ops free, then $0.001/op in USDC on Base
+- **Payments are automatic** — the client detects 402, signs off-chain, retries transparently
+- **No subscriptions** — pay per op, pay as you go
+
+## Installation
+
+```bash
+# Core (read/write with your own encrypted blobs)
+pip install locivault-client
+
+# With built-in payment support (recommended for agents)
+pip install "locivault-client[payments]"
+```
+
+## Quickstart
+
+```python
+from eth_account import Account
+from locivault_client import LocIVaultClient
+
+# Load your wallet (or generate one: Account.create())
+account = Account.from_key("0x<your-private-key>")
+
+# Create the client — payments are automatic
+client = LocIVaultClient(account)
+
+# Write encrypted memory (you encrypt it; LocIVault stores the blob)
+import os
+blob = os.urandom(64)                # your AES-encrypted data
+result = client.write(blob)
+print(result)
+# {'ok': True, 'sha256': '...', 'size': 64, 'ops_used': 1, 'free_ops_remaining': 49}
+
+# Read it back
+retrieved = client.read()
+assert retrieved == blob
+
+# Check status
+print(client.status())
+# {'wallet': '0x...', 'ops_used': 2, 'free_ops_remaining': 48, 'tier': 'free', ...}
+```
+
+## Built-in encryption helper
+
+If you want LocIVault to handle encryption for you using your wallet's private key:
+
+```python
+client = LocIVaultClient(account, auto_encrypt=True)
+
+# Encrypt + store in one call
+client.write_plaintext(b"my agent's memory goes here")
+
+# Retrieve + decrypt in one call
+text = client.read_plaintext()
+print(text)  # b"my agent's memory goes here"
+```
+
+The encryption uses AES-256-GCM with a key derived from your wallet's private key via scrypt. The encrypted blob is what gets stored on LocIVault's servers.
+
+## Manual encryption
+
+Use the `encrypt` / `decrypt` functions directly if you want more control:
+
+```python
+from locivault_client import encrypt, decrypt
+from locivault_client.crypto import derive_key, _extract_private_key
+
+# Derive a stable key from your wallet
+raw_key = _extract_private_key(account)
+
+# Encrypt your data
+blob = encrypt(b"plaintext memory", raw_key)
+
+# Store it
+client.write(blob)
+
+# Later: retrieve and decrypt
+retrieved_blob = client.read()
+plaintext = decrypt(retrieved_blob, raw_key)
+```
+
+## Payment behaviour
+
+LocIVault uses [x402](https://x402.org) for micropayments:
+
+- Every wallet gets **50 free ops** (reads + writes combined)
+- After that: **$0.001 per op** in USDC on Base
+- Payments are signed off-chain (EIP-3009) — **no gas needed**
+- The server settles on-chain; the agent just signs an authorization
+
+With `auto_pay=True` (the default), this is invisible to your code. Set `auto_pay=False` if you want to handle payment explicitly:
+
+```python
+from locivault_client import LocIVaultClient, PaymentRequired
+
+client = LocIVaultClient(account, auto_pay=False)
+
+try:
+    client.write(blob)
+except PaymentRequired as e:
+    print("Free tier exhausted. Payment required.")
+    print("Requirements:", e.accepts)
+    # sign manually and retry with the x_payment header
+```
+
+## Network
+
+Default: **Base Sepolia** (`eip155:84532`) — testnet USDC, no real money.
+
+To use Base mainnet:
+```python
+client = LocIVaultClient(account, network="eip155:8453")
+```
+
+Note: you'll need real USDC on Base mainnet for paid ops.
+
+## Requirements
+
+- Python 3.10+
+- `eth-account` — wallet operations
+- `cryptography` — AES-256-GCM
+- `requests` — HTTP
+- `x402[evm]` — payment signing (optional, required for auto_pay)
+
+## License
+
+MIT

locivault_client-0.1.0/README.md

@@ -0,0 +1,136 @@
+# locivault-client
+
+Python client SDK for [LocIVault](https://locivault.dev) — encrypted, agent-owned memory storage with x402 micropayments.
+
+## What it does
+
+AI agents need memory that persists across sessions and travels with them across platforms. LocIVault stores encrypted blobs identified by wallet address. The agent holds the key. The server never sees plaintext.
+
+- **Encrypted at rest** — AES-256-GCM, key derived from your wallet's private key
+- **x402 micropayments** — first 50 ops free, then $0.001/op in USDC on Base
+- **Payments are automatic** — the client detects 402, signs off-chain, retries transparently
+- **No subscriptions** — pay per op, pay as you go
+
+## Installation
+
+```bash
+# Core (read/write with your own encrypted blobs)
+pip install locivault-client
+
+# With built-in payment support (recommended for agents)
+pip install "locivault-client[payments]"
+```
+
+## Quickstart
+
+```python
+from eth_account import Account
+from locivault_client import LocIVaultClient
+
+# Load your wallet (or generate one: Account.create())
+account = Account.from_key("0x<your-private-key>")
+
+# Create the client — payments are automatic
+client = LocIVaultClient(account)
+
+# Write encrypted memory (you encrypt it; LocIVault stores the blob)
+import os
+blob = os.urandom(64)                # your AES-encrypted data
+result = client.write(blob)
+print(result)
+# {'ok': True, 'sha256': '...', 'size': 64, 'ops_used': 1, 'free_ops_remaining': 49}
+
+# Read it back
+retrieved = client.read()
+assert retrieved == blob
+
+# Check status
+print(client.status())
+# {'wallet': '0x...', 'ops_used': 2, 'free_ops_remaining': 48, 'tier': 'free', ...}
+```
+
+## Built-in encryption helper
+
+If you want LocIVault to handle encryption for you using your wallet's private key:
+
+```python
+client = LocIVaultClient(account, auto_encrypt=True)
+
+# Encrypt + store in one call
+client.write_plaintext(b"my agent's memory goes here")
+
+# Retrieve + decrypt in one call
+text = client.read_plaintext()
+print(text)  # b"my agent's memory goes here"
+```
+
+The encryption uses AES-256-GCM with a key derived from your wallet's private key via scrypt. The encrypted blob is what gets stored on LocIVault's servers.
+
+## Manual encryption
+
+Use the `encrypt` / `decrypt` functions directly if you want more control:
+
+```python
+from locivault_client import encrypt, decrypt
+from locivault_client.crypto import derive_key, _extract_private_key
+
+# Derive a stable key from your wallet
+raw_key = _extract_private_key(account)
+
+# Encrypt your data
+blob = encrypt(b"plaintext memory", raw_key)
+
+# Store it
+client.write(blob)
+
+# Later: retrieve and decrypt
+retrieved_blob = client.read()
+plaintext = decrypt(retrieved_blob, raw_key)
+```
+
+## Payment behaviour
+
+LocIVault uses [x402](https://x402.org) for micropayments:
+
+- Every wallet gets **50 free ops** (reads + writes combined)
+- After that: **$0.001 per op** in USDC on Base
+- Payments are signed off-chain (EIP-3009) — **no gas needed**
+- The server settles on-chain; the agent just signs an authorization
+
+With `auto_pay=True` (the default), this is invisible to your code. Set `auto_pay=False` if you want to handle payment explicitly:
+
+```python
+from locivault_client import LocIVaultClient, PaymentRequired
+
+client = LocIVaultClient(account, auto_pay=False)
+
+try:
+    client.write(blob)
+except PaymentRequired as e:
+    print("Free tier exhausted. Payment required.")
+    print("Requirements:", e.accepts)
+    # sign manually and retry with the x_payment header
+```
+
+## Network
+
+Default: **Base Sepolia** (`eip155:84532`) — testnet USDC, no real money.
+
+To use Base mainnet:
+```python
+client = LocIVaultClient(account, network="eip155:8453")
+```
+
+Note: you'll need real USDC on Base mainnet for paid ops.
+
+## Requirements
+
+- Python 3.10+
+- `eth-account` — wallet operations
+- `cryptography` — AES-256-GCM
+- `requests` — HTTP
+- `x402[evm]` — payment signing (optional, required for auto_pay)
+
+## License
+
+MIT

locivault_client-0.1.0/locivault_client/__init__.py

@@ -0,0 +1,30 @@
+"""
+LocIVault Python Client SDK
+===========================
+
+Encrypted, agent-owned memory storage with x402 micropayments.
+
+Quickstart
+----------
+    from locivault_client import LocIVaultClient
+    from eth_account import Account
+
+    account = Account.from_key("0x...")
+    client = LocIVaultClient(account)
+
+    client.write(b"\\x00\\x01\\x02...")        # your encrypted blob
+    blob = client.read()                       # get it back
+    print(client.status())                     # ops used, tier, etc.
+
+Key custody
+-----------
+LocIVault stores encrypted blobs — it never sees plaintext.
+Encrypt/decrypt your data before passing it to this client.
+Use locivault_client.crypto for a bundled AES-256-GCM helper.
+"""
+
+from .client import LocIVaultClient
+from .crypto import encrypt, decrypt
+
+__all__ = ["LocIVaultClient", "encrypt", "decrypt"]
+__version__ = "0.1.0"

locivault_client-0.1.0/locivault_client/client.py

@@ -0,0 +1,315 @@
+"""
+LocIVaultClient — main client class.
+
+Usage (simple):
+    from locivault_client import LocIVaultClient
+    from eth_account import Account
+
+    account = Account.from_key("0x...")
+    client = LocIVaultClient(account)
+
+    # Write encrypted memory (encrypt it yourself or use the auto_encrypt option)
+    import os
+    blob = os.urandom(64)  # your encrypted bytes
+    result = client.write(blob)
+    print(result)  # {"ok": True, "sha256": "...", "ops_used": 1, ...}
+
+    # Read it back
+    data = client.read()
+
+    # Check account status
+    print(client.status())
+
+Usage (with built-in encryption):
+    from locivault_client import LocIVaultClient
+    from eth_account import Account
+
+    account = Account.from_key("0x...")
+    client = LocIVaultClient(account, auto_encrypt=True)
+
+    client.write_plaintext(b"my secret memory")
+    text = client.read_plaintext()
+
+Payment behaviour:
+    - First 50 ops per wallet are free (no payment needed)
+    - After that, each op costs $0.001 USDC on Base
+    - Payment is automatic when an account is provided — the client
+      detects the 402, signs a payment, and retries transparently
+    - Set auto_pay=False to disable (you'll get PaymentRequired exceptions instead)
+"""
+
+import base64
+import hashlib
+import json
+import logging
+import time
+from typing import Optional
+
+import requests
+
+from .crypto import encrypt_with_account, decrypt_with_account
+from .signing import sign_request
+
+log = logging.getLogger("locivault.client")
+
+# Public server
+DEFAULT_BASE_URL = "https://locivault.fly.dev"
+DEFAULT_NETWORK  = "eip155:84532"   # Base Sepolia (testnet)
+
+# Throttle: don't fire two payments within this many seconds.
+# The x402.org facilitator needs ~3s between settlements to avoid simulation failures.
+PAY_THROTTLE_SEC = 3.5
+
+
+class PaymentRequired(Exception):
+    """
+    Raised when the server returns 402 and auto_pay=False (or no account provided).
+
+    Attributes:
+        accepts (list): the "accepts" list from the 402 body — pass to PaymentSigner.sign()
+        body    (dict): full 402 response body
+    """
+    def __init__(self, accepts: list, body: dict):
+        self.accepts = accepts
+        self.body    = body
+        super().__init__(f"Payment required. Use auto_pay=True or sign manually. Accepts: {accepts}")
+
+
+class LocIVaultError(Exception):
+    """Raised for non-payment API errors (4xx/5xx)."""
+    def __init__(self, status_code: int, detail: str):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"LocIVault error {status_code}: {detail}")
+
+
+class LocIVaultClient:
+    """
+    Python client for the LocIVault API.
+
+    Args:
+        account:      eth_account LocalAccount (your wallet). Used for:
+                        - Wallet address (sent as X-Wallet-Address header)
+                        - Payment signing (when auto_pay=True)
+                        - Encryption key derivation (when auto_encrypt=True)
+        base_url:     LocIVault server URL. Default: https://locivault.fly.dev
+        network:      EIP-155 chain ID string. Default: "eip155:84532" (Base Sepolia)
+        auto_pay:     If True (default), automatically sign and send x402 payments
+                      when the free tier is exhausted. Requires x402[evm] to be installed.
+        auto_encrypt: If True, write_plaintext/read_plaintext will encrypt/decrypt
+                      using the account's private key (AES-256-GCM). Default: False.
+        timeout:      HTTP request timeout in seconds. Default: 30.
+        session:      Optional requests.Session to reuse. If None, a fresh one is created.
+    """
+
+    def __init__(
+        self,
+        account,
+        base_url:      str  = DEFAULT_BASE_URL,
+        network:       str  = DEFAULT_NETWORK,
+        auto_pay:      bool = True,
+        auto_encrypt:  bool = False,
+        timeout:       int  = 30,
+        session:       Optional[requests.Session] = None,
+    ):
+        self.account      = account
+        self.base_url     = base_url.rstrip("/")
+        self.network      = network
+        self.auto_pay     = auto_pay
+        self.auto_encrypt = auto_encrypt
+        self.timeout      = timeout
+        self._session     = session or requests.Session()
+        self._signer      = None          # lazy — only built if payment needed
+        self._last_pay_ts = 0.0           # for payment throttling
+
+    # ── Public API ─────────────────────────────────────────────────────────────
+
+    def write(self, data: bytes) -> dict:
+        """
+        Store an encrypted blob for this wallet.
+
+        Args:
+            data: arbitrary bytes (client-side encrypted — LocIVault never sees plaintext)
+
+        Returns:
+            dict with keys: ok, sha256, size, ops_used, free_ops_remaining
+
+        Raises:
+            PaymentRequired: if auto_pay=False and free tier is exhausted
+            LocIVaultError:  on 4xx/5xx errors
+        """
+        return self._request_with_payment(
+            method="POST",
+            path="/write",
+            json_body={"data": base64.b64encode(data).decode()},
+            resource_path="/write",
+        )
+
+    def read(self) -> bytes:
+        """
+        Retrieve the stored encrypted blob for this wallet.
+
+        Returns:
+            bytes: the blob previously stored with write()
+
+        Raises:
+            PaymentRequired: if auto_pay=False and free tier is exhausted
+            LocIVaultError:  on 4xx/5xx errors (404 if nothing stored yet)
+        """
+        result = self._request_with_payment(
+            method="GET",
+            path="/read",
+            resource_path="/read",
+        )
+        return base64.b64decode(result["data"])
+
+    def write_plaintext(self, plaintext: bytes) -> dict:
+        """
+        Encrypt plaintext with this wallet's key and store it.
+
+        Requires auto_encrypt=True (or just call this directly — it will work
+        regardless of the auto_encrypt flag, using the account's private key).
+
+        Args:
+            plaintext: bytes to encrypt and store
+
+        Returns:
+            dict: same as write()
+        """
+        blob = encrypt_with_account(plaintext, self.account)
+        return self.write(blob)
+
+    def read_plaintext(self) -> bytes:
+        """
+        Read and decrypt stored memory using this wallet's key.
+
+        Returns:
+            bytes: original plaintext
+
+        Raises:
+            ValueError: if decryption fails (wrong key or tampered blob)
+        """
+        blob = self.read()
+        return decrypt_with_account(blob, self.account)
+
+    def status(self, wallet: Optional[str] = None) -> dict:
+        """
+        Check ops usage and tier for a wallet address.
+
+        Args:
+            wallet: wallet address to check. Defaults to this client's account address.
+
+        Returns:
+            dict with keys: wallet, ops_used, free_ops_remaining, tier, price_per_op, ...
+        """
+        addr = wallet or self.account.address
+        resp = self._session.get(
+            f"{self.base_url}/status",
+            headers={"X-Wallet-Address": addr},
+            timeout=self.timeout,
+        )
+        return resp.json()
+
+    def health(self) -> dict:
+        """Liveness check. Returns {"status": "ok", "ts": "..."}."""
+        resp = self._session.get(f"{self.base_url}/health", timeout=self.timeout)
+        resp.raise_for_status()
+        return resp.json()
+
+    # ── Internal helpers ───────────────────────────────────────────────────────
+
+    def _request_with_payment(
+        self,
+        method:        str,
+        path:          str,
+        resource_path: str,
+        json_body:     Optional[dict] = None,
+    ) -> dict:
+        """
+        Make an API request. If the server returns 402 and auto_pay=True,
+        sign a payment and retry exactly once.
+        Every request is signed with the wallet key for authentication.
+        """
+        sig_headers = sign_request(self.account, method, path)
+        headers = {"X-Wallet-Address": self.account.address, **sig_headers}
+
+        # First attempt — no payment header
+        resp = self._do_request(method, path, headers, json_body)
+
+        if resp.status_code == 200:
+            return resp.json()
+
+        if resp.status_code == 402:
+            body_402 = resp.json()
+            accepts  = body_402.get("accepts", [])
+
+            if not self.auto_pay:
+                raise PaymentRequired(accepts=accepts, body=body_402)
+
+            if not accepts:
+                raise LocIVaultError(402, "Server returned 402 with no payment requirements")
+
+            # Re-sign with fresh timestamp + add payment header
+            sig_headers = sign_request(self.account, method, path)
+            payment_header = self._sign_payment(
+                resource_url=f"{self.base_url}{resource_path}",
+                accepts=accepts,
+            )
+            headers = {
+                "X-Wallet-Address": self.account.address,
+                **sig_headers,
+                "X-Payment": payment_header,
+            }
+            resp = self._do_request(method, path, headers, json_body)
+
+            if resp.status_code == 200:
+                return resp.json()
+            elif resp.status_code == 402:
+                # Payment was rejected — surface the error
+                detail = resp.json().get("error_detail", resp.text[:200])
+                raise LocIVaultError(402, f"Payment rejected by server: {detail}")
+            else:
+                self._raise_for_status(resp)
+
+        else:
+            self._raise_for_status(resp)
+
+    def _do_request(
+        self,
+        method:    str,
+        path:      str,
+        headers:   dict,
+        json_body: Optional[dict],
+    ) -> requests.Response:
+        url = f"{self.base_url}{path}"
+        if method == "POST":
+            return self._session.post(url, json=json_body, headers=headers, timeout=self.timeout)
+        elif method == "GET":
+            return self._session.get(url, headers=headers, timeout=self.timeout)
+        else:
+            raise ValueError(f"Unsupported method: {method}")
+
+    def _sign_payment(self, resource_url: str, accepts: list) -> str:
+        """Build signer lazily, throttle, sign, return X-Payment header value."""
+        if self._signer is None:
+            from .payment import PaymentSigner
+            self._signer = PaymentSigner(self.account, network=self.network)
+
+        # Throttle: ensure >= PAY_THROTTLE_SEC between payments
+        elapsed = time.time() - self._last_pay_ts
+        if elapsed < PAY_THROTTLE_SEC:
+            wait = PAY_THROTTLE_SEC - elapsed
+            log.debug(f"Throttling payment: sleeping {wait:.1f}s")
+            time.sleep(wait)
+
+        header = self._signer.sign(resource_url, accepts)
+        self._last_pay_ts = time.time()
+        return header
+
+    @staticmethod
+    def _raise_for_status(resp: requests.Response):
+        try:
+            detail = resp.json().get("detail", resp.text[:300])
+        except Exception:
+            detail = resp.text[:300]
+        raise LocIVaultError(resp.status_code, detail)

locivault_client-0.1.0/locivault_client/crypto.py

@@ -0,0 +1,159 @@
+"""
+AES-256-GCM encryption helpers for LocIVault clients.
+
+Key derivation: scrypt(wallet_private_key, salt) → 32-byte AES key
+Blob format (v1):  4-byte magic | 1-byte version | 32-byte salt | 12-byte nonce | ciphertext+GCM-tag
+
+This matches the format used by agentmem_core.py (Mnemis's own memory layer),
+so a LocIVault client using these helpers is byte-for-byte compatible with the
+agentmem stack.
+
+Usage:
+    from eth_account import Account
+    from locivault_client.crypto import derive_key, encrypt, decrypt
+
+    account = Account.from_key("0x...")
+    key = derive_key(account)
+
+    blob = encrypt(b"plaintext", key)
+    text = decrypt(blob, key)
+"""
+
+import os
+import struct
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.scrypt import Scrypt
+from cryptography.hazmat.backends import default_backend
+
+# Binary format constants
+MAGIC   = b'\xA6\xE1\x4D\x00'
+VERSION = b'\x01'
+HEADER  = MAGIC + VERSION   # 5 bytes
+
+# scrypt params — same as agentmem_core
+SCRYPT_N = 2**17
+SCRYPT_R = 8
+SCRYPT_P = 1
+
+
+def derive_key(private_key_bytes: bytes, salt: bytes) -> bytes:
+    """
+    Derive a 32-byte AES key from a wallet private key + salt via scrypt.
+
+    Args:
+        private_key_bytes: raw 32-byte wallet private key
+        salt:              32-byte random salt (generated fresh per encrypt call)
+
+    Returns:
+        32-byte AES-256 key
+    """
+    kdf = Scrypt(
+        salt=salt,
+        length=32,
+        n=SCRYPT_N,
+        r=SCRYPT_R,
+        p=SCRYPT_P,
+        backend=default_backend(),
+    )
+    return kdf.derive(private_key_bytes)
+
+
+def encrypt(plaintext: bytes, key: bytes) -> bytes:
+    """
+    Encrypt plaintext with AES-256-GCM. Returns a self-contained binary blob.
+
+    The blob includes the salt and nonce — no external state needed to decrypt.
+    Fresh salt per call = different derived key per call (forward secrecy).
+
+    Args:
+        plaintext: arbitrary bytes to encrypt
+        key:       32-byte AES key (e.g. from derive_key())
+
+    Returns:
+        bytes: encrypted blob in LocIVault v1 format
+    """
+    salt  = os.urandom(32)
+    nonce = os.urandom(12)
+    derived = derive_key(key, salt)   # note: key here = private key seed
+    ciphertext = AESGCM(derived).encrypt(nonce, plaintext, None)
+    return HEADER + salt + nonce + ciphertext
+
+
+def decrypt(blob: bytes, key: bytes) -> bytes:
+    """
+    Decrypt a LocIVault v1 encrypted blob.
+
+    Args:
+        blob: bytes from encrypt() or from the /read endpoint
+        key:  32-byte AES key seed (same value passed to encrypt)
+
+    Returns:
+        bytes: original plaintext
+
+    Raises:
+        ValueError: if magic/version don't match, or AESGCM authentication fails
+    """
+    if len(blob) < 5 + 32 + 12 + 16:
+        raise ValueError(f"Blob too short ({len(blob)} bytes)")
+    if blob[:4] != MAGIC:
+        raise ValueError("Not a LocIVault blob (bad magic)")
+    if blob[4:5] != VERSION:
+        raise ValueError(f"Unknown blob version: {blob[4]:#x}")
+
+    salt       = blob[5:37]
+    nonce      = blob[37:49]
+    ciphertext = blob[49:]
+
+    derived = derive_key(key, salt)
+    try:
+        return AESGCM(derived).decrypt(nonce, ciphertext, None)
+    except Exception as e:
+        raise ValueError(f"Decryption failed (wrong key or tampered blob): {e}") from e
+
+
+# ── convenience wrappers that take an eth_account.Account directly ────────────
+
+def encrypt_with_account(plaintext: bytes, account) -> bytes:
+    """
+    Encrypt using an eth_account Account's private key.
+
+    Args:
+        plaintext: bytes to encrypt
+        account:   eth_account.Account instance (must have ._private_key)
+
+    Returns:
+        encrypted blob bytes
+    """
+    raw_key = _extract_private_key(account)
+    return encrypt(plaintext, raw_key)
+
+
+def decrypt_with_account(blob: bytes, account) -> bytes:
+    """
+    Decrypt using an eth_account Account's private key.
+
+    Args:
+        blob:    encrypted blob bytes
+        account: eth_account.Account instance
+
+    Returns:
+        plaintext bytes
+    """
+    raw_key = _extract_private_key(account)
+    return decrypt(blob, raw_key)
+
+
+def _extract_private_key(account) -> bytes:
+    """Extract raw 32-byte private key from an eth_account LocalAccount."""
+    # eth_account stores it as _private_key (HexBytes or bytes)
+    pk = getattr(account, '_private_key', None) or getattr(account, 'key', None)
+    if pk is None:
+        raise ValueError(
+            "Could not extract private key from account object. "
+            "Expected eth_account.LocalAccount with ._private_key attribute."
+        )
+    if isinstance(pk, (bytes, bytearray)):
+        return bytes(pk)
+    # HexBytes or other hex-string type
+    return bytes.fromhex(str(pk).removeprefix("0x"))

locivault_client-0.1.0/locivault_client/payment.py

@@ -0,0 +1,77 @@
+"""
+x402 payment signing for LocIVault.
+
+This module handles the client side of x402:
+  1. Parse the 402 response body to get payment requirements
+  2. Sign an EIP-3009 authorization off-chain (no gas needed)
+  3. Return a JSON string suitable for the X-Payment header
+
+The server verifies + settles on its end. The agent never submits a transaction.
+Network: Base Sepolia (eip155:84532) for testnet, Base mainnet (eip155:8453) for prod.
+"""
+
+import time
+import json
+import logging
+
+log = logging.getLogger("locivault.payment")
+
+try:
+    from x402.client import x402ClientSync
+    from x402.mechanisms.evm.exact import ExactEvmScheme
+    from x402.mechanisms.evm.signers import EthAccountSigner
+    from x402.schemas.payments import PaymentRequired, PaymentRequirements
+    _X402_AVAILABLE = True
+except ImportError:
+    _X402_AVAILABLE = False
+
+
+class PaymentSigner:
+    """
+    Signs x402 payment authorizations for LocIVault ops.
+
+    Args:
+        account: eth_account LocalAccount (the payer)
+        network: EIP-155 chain ID string, e.g. "eip155:84532" (Base Sepolia)
+    """
+
+    def __init__(self, account, network: str = "eip155:84532"):
+        if not _X402_AVAILABLE:
+            raise ImportError(
+                "x402 is required for payment signing. "
+                "Install it with: pip install 'x402[evm]'"
+            )
+        self.network = network
+        signer = EthAccountSigner(account)
+        self._client = x402ClientSync()
+        self._client.register(network, ExactEvmScheme(signer=signer))
+
+    def sign(self, resource_url: str, accepts: list) -> str:
+        """
+        Sign a payment for the given resource.
+
+        Args:
+            resource_url: full URL of the resource being paid for (e.g. https://locivault.fly.dev/write)
+            accepts:      the "accepts" list from the 402 response body
+
+        Returns:
+            JSON string to use as the X-Payment header value
+        """
+        acc = accepts[0]
+        requirements = PaymentRequirements(
+            scheme=acc["scheme"],
+            network=acc["network"],
+            asset=acc["asset"],
+            amount=str(acc["amount"]),
+            pay_to=acc["payTo"],
+            max_timeout_seconds=acc.get("maxTimeoutSeconds", 300),
+            extra=acc.get("extra"),
+            resource=resource_url,
+            description="LocIVault op",
+            mime_type="application/json",
+            output_schema=None,
+            request_hash="",
+        )
+        payment_required = PaymentRequired(x402_version=2, accepts=[requirements])
+        payload = self._client.create_payment_payload(payment_required)
+        return payload.model_dump_json()

locivault_client-0.1.0/locivault_client/signing.py

@@ -0,0 +1,121 @@
+"""
+Request signing for LocIVault.
+
+Every write/read request is signed with the agent's wallet key.
+The server verifies the signature matches the X-Wallet-Address header.
+
+WHY: Without signing, anyone who knows a wallet address can overwrite that
+agent's memory (address is not secret). With signing, only the holder of
+the private key can write/read — the address IS a verifiable identity.
+
+Signature scheme:
+  message = SHA256( wallet_address_lower + ":" + timestamp_str + ":" + method_upper + ":" + path )
+  signature = eth_account sign_message(Ethereum signed message prefix + message)
+  
+Headers added to every authenticated request:
+  X-Wallet-Address: 0x...   (already present)
+  X-Timestamp:      1234567890   (Unix seconds, UTC)
+  X-Signature:      0x...   (65-byte hex ECDSA sig)
+
+Server verification:
+  1. Parse X-Wallet-Address, X-Timestamp, X-Signature
+  2. Reject if abs(now - timestamp) > TIMESTAMP_TOLERANCE_SEC (60s default) — replay protection
+  3. Reconstruct the same message, recover signer address from signature
+  4. Reject if recovered address != X-Wallet-Address (case-insensitive)
+"""
+
+import hashlib
+import time
+from eth_account import Account
+from eth_account.messages import encode_defunct
+
+
+TIMESTAMP_TOLERANCE_SEC = 60
+
+
+def _build_message(wallet: str, timestamp: int, method: str, path: str) -> bytes:
+    """Build the canonical message bytes to sign/verify."""
+    raw = f"{wallet.lower()}:{timestamp}:{method.upper()}:{path}"
+    return hashlib.sha256(raw.encode()).digest()
+
+
+def sign_request(account, method: str, path: str) -> dict:
+    """
+    Sign a request. Returns headers dict with X-Timestamp and X-Signature.
+
+    Args:
+        account:  eth_account LocalAccount
+        method:   HTTP method string ("GET", "POST", etc.)
+        path:     URL path being requested (e.g. "/write")
+
+    Returns:
+        dict of extra headers to merge into the request:
+        {"X-Timestamp": "...", "X-Signature": "0x..."}
+    """
+    ts = int(time.time())
+    msg_bytes = _build_message(account.address, ts, method, path)
+    signable = encode_defunct(primitive=msg_bytes)
+    signed = account.sign_message(signable)
+    return {
+        "X-Timestamp": str(ts),
+        "X-Signature": signed.signature.hex(),
+    }
+
+
+def verify_request_signature(
+    wallet_address: str,
+    timestamp_str: str,
+    signature_hex: str,
+    method: str,
+    path: str,
+    tolerance_sec: int = TIMESTAMP_TOLERANCE_SEC,
+) -> tuple[bool, str]:
+    """
+    Verify a signed request on the server side.
+
+    Args:
+        wallet_address:  from X-Wallet-Address header
+        timestamp_str:   from X-Timestamp header
+        signature_hex:   from X-Signature header (hex with or without 0x)
+        method:          HTTP method
+        path:            URL path
+        tolerance_sec:   max age of timestamp before rejection
+
+    Returns:
+        (True, "") if valid
+        (False, reason_string) if invalid
+    """
+    # --- parse timestamp ---
+    try:
+        ts = int(timestamp_str)
+    except (ValueError, TypeError):
+        return False, "X-Timestamp is not a valid integer"
+
+    age = abs(time.time() - ts)
+    if age > tolerance_sec:
+        return False, f"X-Timestamp too old or in future (age={age:.0f}s, tolerance={tolerance_sec}s)"
+
+    # --- parse signature ---
+    sig = signature_hex
+    if sig.startswith("0x"):
+        sig = sig[2:]
+    try:
+        sig_bytes = bytes.fromhex(sig)
+    except ValueError:
+        return False, "X-Signature is not valid hex"
+
+    if len(sig_bytes) != 65:
+        return False, f"X-Signature must be 65 bytes, got {len(sig_bytes)}"
+
+    # --- recover signer ---
+    msg_bytes = _build_message(wallet_address, ts, method, path)
+    signable = encode_defunct(primitive=msg_bytes)
+    try:
+        recovered = Account.recover_message(signable, signature=sig_bytes)
+    except Exception as e:
+        return False, f"Signature recovery failed: {e}"
+
+    if recovered.lower() != wallet_address.lower():
+        return False, f"Signature mismatch: signed by {recovered}, expected {wallet_address}"
+
+    return True, ""

locivault_client-0.1.0/locivault_client.egg-info/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: locivault-client
+Version: 0.1.0
+Summary: Python client for LocIVault — encrypted, agent-owned memory with x402 micropayments
+License: MIT
+Project-URL: Homepage, https://locivault.dev
+Project-URL: Repository, https://github.com/locivault/locivault-python
+Project-URL: Bug Tracker, https://github.com/locivault/locivault-python/issues
+Keywords: ai,agent,memory,encryption,x402,web3,locivault
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Requires-Dist: cryptography>=41
+Requires-Dist: eth-account>=0.10
+Provides-Extra: payments
+Requires-Dist: x402[evm]>=2.5; extra == "payments"
+Provides-Extra: all
+Requires-Dist: x402[evm]>=2.5; extra == "all"
+
+# locivault-client
+
+Python client SDK for [LocIVault](https://locivault.dev) — encrypted, agent-owned memory storage with x402 micropayments.
+
+## What it does
+
+AI agents need memory that persists across sessions and travels with them across platforms. LocIVault stores encrypted blobs identified by wallet address. The agent holds the key. The server never sees plaintext.
+
+- **Encrypted at rest** — AES-256-GCM, key derived from your wallet's private key
+- **x402 micropayments** — first 50 ops free, then $0.001/op in USDC on Base
+- **Payments are automatic** — the client detects 402, signs off-chain, retries transparently
+- **No subscriptions** — pay per op, pay as you go
+
+## Installation
+
+```bash
+# Core (read/write with your own encrypted blobs)
+pip install locivault-client
+
+# With built-in payment support (recommended for agents)
+pip install "locivault-client[payments]"
+```
+
+## Quickstart
+
+```python
+from eth_account import Account
+from locivault_client import LocIVaultClient
+
+# Load your wallet (or generate one: Account.create())
+account = Account.from_key("0x<your-private-key>")
+
+# Create the client — payments are automatic
+client = LocIVaultClient(account)
+
+# Write encrypted memory (you encrypt it; LocIVault stores the blob)
+import os
+blob = os.urandom(64)                # your AES-encrypted data
+result = client.write(blob)
+print(result)
+# {'ok': True, 'sha256': '...', 'size': 64, 'ops_used': 1, 'free_ops_remaining': 49}
+
+# Read it back
+retrieved = client.read()
+assert retrieved == blob
+
+# Check status
+print(client.status())
+# {'wallet': '0x...', 'ops_used': 2, 'free_ops_remaining': 48, 'tier': 'free', ...}
+```
+
+## Built-in encryption helper
+
+If you want LocIVault to handle encryption for you using your wallet's private key:
+
+```python
+client = LocIVaultClient(account, auto_encrypt=True)
+
+# Encrypt + store in one call
+client.write_plaintext(b"my agent's memory goes here")
+
+# Retrieve + decrypt in one call
+text = client.read_plaintext()
+print(text)  # b"my agent's memory goes here"
+```
+
+The encryption uses AES-256-GCM with a key derived from your wallet's private key via scrypt. The encrypted blob is what gets stored on LocIVault's servers.
+
+## Manual encryption
+
+Use the `encrypt` / `decrypt` functions directly if you want more control:
+
+```python
+from locivault_client import encrypt, decrypt
+from locivault_client.crypto import derive_key, _extract_private_key
+
+# Derive a stable key from your wallet
+raw_key = _extract_private_key(account)
+
+# Encrypt your data
+blob = encrypt(b"plaintext memory", raw_key)
+
+# Store it
+client.write(blob)
+
+# Later: retrieve and decrypt
+retrieved_blob = client.read()
+plaintext = decrypt(retrieved_blob, raw_key)
+```
+
+## Payment behaviour
+
+LocIVault uses [x402](https://x402.org) for micropayments:
+
+- Every wallet gets **50 free ops** (reads + writes combined)
+- After that: **$0.001 per op** in USDC on Base
+- Payments are signed off-chain (EIP-3009) — **no gas needed**
+- The server settles on-chain; the agent just signs an authorization
+
+With `auto_pay=True` (the default), this is invisible to your code. Set `auto_pay=False` if you want to handle payment explicitly:
+
+```python
+from locivault_client import LocIVaultClient, PaymentRequired
+
+client = LocIVaultClient(account, auto_pay=False)
+
+try:
+    client.write(blob)
+except PaymentRequired as e:
+    print("Free tier exhausted. Payment required.")
+    print("Requirements:", e.accepts)
+    # sign manually and retry with the x_payment header
+```
+
+## Network
+
+Default: **Base Sepolia** (`eip155:84532`) — testnet USDC, no real money.
+
+To use Base mainnet:
+```python
+client = LocIVaultClient(account, network="eip155:8453")
+```
+
+Note: you'll need real USDC on Base mainnet for paid ops.
+
+## Requirements
+
+- Python 3.10+
+- `eth-account` — wallet operations
+- `cryptography` — AES-256-GCM
+- `requests` — HTTP
+- `x402[evm]` — payment signing (optional, required for auto_pay)
+
+## License
+
+MIT

locivault_client-0.1.0/locivault_client.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+locivault_client/__init__.py
+locivault_client/client.py
+locivault_client/crypto.py
+locivault_client/payment.py
+locivault_client/signing.py
+locivault_client.egg-info/PKG-INFO
+locivault_client.egg-info/SOURCES.txt
+locivault_client.egg-info/dependency_links.txt
+locivault_client.egg-info/requires.txt
+locivault_client.egg-info/top_level.txt

locivault_client-0.1.0/locivault_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

locivault_client-0.1.0/locivault_client.egg-info/requires.txt

@@ -0,0 +1,9 @@
+requests>=2.28
+cryptography>=41
+eth-account>=0.10
+
+[all]
+x402[evm]>=2.5
+
+[payments]
+x402[evm]>=2.5

locivault_client-0.1.0/locivault_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+locivault_client

locivault_client-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "locivault-client"
+version = "0.1.0"
+description = "Python client for LocIVault — encrypted, agent-owned memory with x402 micropayments"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+keywords = ["ai", "agent", "memory", "encryption", "x402", "web3", "locivault"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security :: Cryptography",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests>=2.28",
+    "cryptography>=41",
+    "eth-account>=0.10",
+]
+
+[project.optional-dependencies]
+payments = [
+    "x402[evm]>=2.5",
+]
+all = [
+    "x402[evm]>=2.5",
+]
+
+[project.urls]
+Homepage    = "https://locivault.dev"
+Repository  = "https://github.com/locivault/locivault-python"
+"Bug Tracker" = "https://github.com/locivault/locivault-python/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["locivault_client*"]

locivault_client-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+