@agentlayer.tech/wallet 0.1.0

package/agent-wallet/agent_wallet/approval.py

@@ -0,0 +1,161 @@
+"""Host-issued approval tokens for sensitive wallet actions."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+from typing import Any
+
+from agent_wallet.config import resolve_approval_secret, settings
+from agent_wallet.wallet_layer.base import WalletBackendError
+
+APPROVAL_TOKEN_VERSION = 1
+
+
+def _canonical_json(payload: dict[str, Any]) -> bytes:
+    return json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+def _urlsafe_b64(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")
+
+
+def _urlsafe_b64_decode(data: str) -> bytes:
+    padding = "=" * (-len(data) % 4)
+    return base64.urlsafe_b64decode(data + padding)
+
+
+def _sign_payload(payload: dict[str, Any], secret: str) -> str:
+    digest = hmac.new(secret.encode("utf-8"), _canonical_json(payload), hashlib.sha256).digest()
+    return _urlsafe_b64(digest)
+
+
+def _approval_secret() -> str:
+    secret = resolve_approval_secret().strip()
+    if not secret:
+        raise WalletBackendError(
+            "Execute mode requires AGENT_WALLET_BOOT_KEY and a sealed approval_secret. "
+            "The host must issue approval tokens after explicit user confirmation."
+        )
+    return secret
+
+
+def build_operation_binding(*, tool_name: str, network: str, summary: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "tool": tool_name,
+        "network": str(network).strip().lower(),
+        "summary": summary,
+    }
+
+
+def issue_approval_token(
+    *,
+    tool_name: str,
+    network: str,
+    summary: dict[str, Any],
+    mainnet_confirmed: bool = False,
+    ttl_seconds: int | None = None,
+    issued_by: str = "host",
+) -> str:
+    secret = _approval_secret()
+    now = int(time.time())
+    ttl = ttl_seconds if ttl_seconds is not None else int(settings.agent_wallet_approval_ttl_seconds)
+    if ttl <= 0:
+        raise WalletBackendError("Approval token ttl must be greater than zero.")
+
+    payload = {
+        "v": APPROVAL_TOKEN_VERSION,
+        "iat": now,
+        "exp": now + ttl,
+        "issued_by": issued_by,
+        "binding": build_operation_binding(tool_name=tool_name, network=network, summary=summary),
+        "mainnet_confirmed": bool(mainnet_confirmed),
+    }
+    signature = _sign_payload(payload, secret)
+    return f"{_urlsafe_b64(_canonical_json(payload))}.{signature}"
+
+
+def verify_approval_token(
+    token: str,
+    *,
+    tool_name: str,
+    network: str,
+    summary: dict[str, Any],
+    require_mainnet_confirmation: bool,
+) -> dict[str, Any]:
+    secret = _approval_secret()
+    if not isinstance(token, str) or "." not in token:
+        raise WalletBackendError("A valid approval_token is required for execute mode.")
+
+    encoded_payload, encoded_sig = token.split(".", 1)
+    try:
+        payload = json.loads(_urlsafe_b64_decode(encoded_payload).decode("utf-8"))
+    except Exception as exc:
+        raise WalletBackendError("approval_token could not be parsed.") from exc
+
+    if not isinstance(payload, dict) or int(payload.get("v") or 0) != APPROVAL_TOKEN_VERSION:
+        raise WalletBackendError("approval_token version is invalid.")
+
+    expected_sig = _sign_payload(payload, secret)
+    if not hmac.compare_digest(encoded_sig, expected_sig):
+        raise WalletBackendError("approval_token signature is invalid.")
+
+    now = int(time.time())
+    if int(payload.get("exp") or 0) < now:
+        raise WalletBackendError("approval_token has expired.")
+
+    expected_binding = build_operation_binding(tool_name=tool_name, network=network, summary=summary)
+    if payload.get("binding") != expected_binding:
+        raise WalletBackendError(
+            "approval_token does not match the requested operation. Generate a new approval after previewing the exact action."
+        )
+    if require_mainnet_confirmation and payload.get("mainnet_confirmed") is not True:
+        raise WalletBackendError("approval_token is missing explicit mainnet confirmation.")
+    return payload
+
+
+def inspect_approval_token(
+    token: str,
+    *,
+    tool_name: str,
+    network: str,
+    require_mainnet_confirmation: bool,
+) -> dict[str, Any]:
+    secret = _approval_secret()
+    if not isinstance(token, str) or "." not in token:
+        raise WalletBackendError("A valid approval_token is required for execute mode.")
+
+    encoded_payload, encoded_sig = token.split(".", 1)
+    try:
+        payload = json.loads(_urlsafe_b64_decode(encoded_payload).decode("utf-8"))
+    except Exception as exc:
+        raise WalletBackendError("approval_token could not be parsed.") from exc
+
+    if not isinstance(payload, dict) or int(payload.get("v") or 0) != APPROVAL_TOKEN_VERSION:
+        raise WalletBackendError("approval_token version is invalid.")
+
+    expected_sig = _sign_payload(payload, secret)
+    if not hmac.compare_digest(encoded_sig, expected_sig):
+        raise WalletBackendError("approval_token signature is invalid.")
+
+    now = int(time.time())
+    if int(payload.get("exp") or 0) < now:
+        raise WalletBackendError("approval_token has expired.")
+
+    binding = payload.get("binding")
+    if not isinstance(binding, dict):
+        raise WalletBackendError("approval_token binding is invalid.")
+    if str(binding.get("tool") or "") != tool_name:
+        raise WalletBackendError(
+            "approval_token does not match the requested operation. Generate a new approval after previewing the exact action."
+        )
+    if str(binding.get("network") or "").strip().lower() != str(network).strip().lower():
+        raise WalletBackendError(
+            "approval_token does not match the requested operation. Generate a new approval after previewing the exact action."
+        )
+    if require_mainnet_confirmation and payload.get("mainnet_confirmed") is not True:
+        raise WalletBackendError("approval_token is missing explicit mainnet confirmation.")
+    return payload

package/agent-wallet/agent_wallet/bootstrap.py

@@ -0,0 +1,178 @@
+"""Bootstrap helpers for provisioning agent wallets on first use."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from agent_wallet.config import refuse_mainnet_wallet_recreation
+from agent_wallet.file_ops import atomic_write_text
+from agent_wallet.wallet_layer.base import WalletBackendError
+from agent_wallet.wallet_layer.base58 import b58encode
+
+WALLET_ADDRESS_PIN_KIND = "openclaw-agent-wallet-address-pin"
+WALLET_ADDRESS_PIN_VERSION = 1
+
+
+def _keypair_bytes_for_file(secret_key: bytes, public_key: bytes) -> list[int]:
+    return list(secret_key + public_key)
+
+
+def generate_solana_wallet_material() -> dict[str, str]:
+    """Generate new Solana secret material without writing it to disk."""
+    try:
+        from nacl.signing import SigningKey
+    except ImportError as exc:
+        raise WalletBackendError(
+            "PyNaCl is required to auto-create a local Solana wallet."
+        ) from exc
+
+    signing_key = SigningKey.generate()
+    secret_key = signing_key.encode()
+    public_key = bytes(signing_key.verify_key)
+    return {
+        "address": b58encode(public_key),
+        "secret_material": json.dumps(_keypair_bytes_for_file(secret_key, public_key), indent=2),
+    }
+
+
+def create_solana_wallet_file(path: Path) -> dict[str, str]:
+    """Create a new local Solana wallet file in Solana CLI JSON format."""
+    material = generate_solana_wallet_material()
+    atomic_write_text(path, material["secret_material"], mode=0o600)
+    return {
+        "address": material["address"],
+        "path": str(path),
+    }
+
+
+def resolve_wallet_pin_path(path: Path) -> Path:
+    """Return the sidecar file used to pin an expected wallet address."""
+    return path.with_suffix(f"{path.suffix}.pin.json")
+
+
+def load_wallet_pin(path: Path) -> dict[str, str] | None:
+    """Load wallet pin metadata if present and valid."""
+    pin_path = resolve_wallet_pin_path(path)
+    if not pin_path.exists():
+        return None
+    try:
+        payload = json.loads(pin_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise WalletBackendError(f"Wallet pin file is malformed: {pin_path}") from exc
+    if not isinstance(payload, dict):
+        raise WalletBackendError(f"Wallet pin file is malformed: {pin_path}")
+    if payload.get("kind") != WALLET_ADDRESS_PIN_KIND:
+        raise WalletBackendError(f"Wallet pin file kind is invalid: {pin_path}")
+    if int(payload.get("version") or 0) != WALLET_ADDRESS_PIN_VERSION:
+        raise WalletBackendError(f"Wallet pin file version is invalid: {pin_path}")
+    address = str(payload.get("address") or "").strip()
+    network = str(payload.get("network") or "").strip().lower()
+    if not address or not network:
+        raise WalletBackendError(f"Wallet pin file is incomplete: {pin_path}")
+    return {
+        "address": address,
+        "network": network,
+        "path": str(pin_path),
+    }
+
+
+def write_wallet_pin(path: Path, *, address: str, network: str) -> dict[str, str]:
+    """Persist the expected wallet address for later mismatch checks."""
+    payload = {
+        "kind": WALLET_ADDRESS_PIN_KIND,
+        "version": WALLET_ADDRESS_PIN_VERSION,
+        "address": address,
+        "network": network.strip().lower(),
+        "wallet_file": path.name,
+    }
+    pin_path = resolve_wallet_pin_path(path)
+    atomic_write_text(pin_path, json.dumps(payload, indent=2), mode=0o600)
+    return {
+        "address": address,
+        "network": payload["network"],
+        "path": str(pin_path),
+    }
+
+
+def ensure_wallet_pin(path: Path, *, address: str, network: str) -> dict[str, str]:
+    """Ensure the wallet pin exists and matches the expected address."""
+    expected_network = network.strip().lower()
+    existing = load_wallet_pin(path)
+    if existing is None:
+        return write_wallet_pin(path, address=address, network=expected_network)
+    if existing["network"] != expected_network:
+        raise WalletBackendError(
+            f"Wallet pin network mismatch for {path}: expected {expected_network}, found {existing['network']}."
+        )
+    if existing["address"] != address:
+        raise WalletBackendError(
+            f"Wallet address mismatch for {path}: pinned {existing['address']}, derived {address}."
+        )
+    return existing
+
+
+def refuse_recreation_if_pinned(path: Path, *, network: str) -> None:
+    """Refuse to recreate a wallet when a mainnet address is already pinned."""
+    expected_network = network.strip().lower()
+    if expected_network != "mainnet" or not refuse_mainnet_wallet_recreation():
+        return
+    existing = load_wallet_pin(path)
+    if existing is None:
+        return
+    raise WalletBackendError(
+        "Refusing to create a new mainnet wallet because a pinned wallet address already exists "
+        f"for {path}. Restore the original wallet file for {existing['address']} instead of creating a new one."
+    )
+
+
+def ensure_solana_wallet_ready() -> dict[str, str] | None:
+    """Ensure that a Solana wallet exists when auto-create is enabled."""
+    from agent_wallet.config import default_solana_wallet_path, resolve_solana_private_key, settings
+
+    if settings.agent_wallet_backend.strip().lower() not in {"solana", "solana_local", "solana-local"}:
+        return None
+
+    if resolve_solana_private_key():
+        return {"address": "", "path": ""}
+
+    configured_path = settings.solana_agent_keypair_path.strip()
+    path = Path(configured_path).expanduser() if configured_path else default_solana_wallet_path(settings.solana_network)
+
+    if path.exists():
+        return {"address": "", "path": str(path)}
+
+    if not settings.solana_auto_create_wallet:
+        return None
+
+    refuse_recreation_if_pinned(path, network=settings.solana_network)
+    created = create_solana_wallet_file(path)
+    write_wallet_pin(path, address=created["address"], network=settings.solana_network)
+    return created
+
+
+def describe_bootstrap() -> dict[str, str | bool]:
+    """Return the effective bootstrap configuration for installer/runtime usage."""
+    from agent_wallet.config import (
+        default_solana_wallet_path,
+        resolve_solana_rpc_url,
+        resolve_runtime_solana_rpc_urls,
+        settings,
+    )
+
+    configured_path = settings.solana_agent_keypair_path.strip()
+    path = Path(configured_path).expanduser() if configured_path else default_solana_wallet_path(settings.solana_network)
+    rpc_urls = resolve_runtime_solana_rpc_urls(
+        settings.solana_network,
+        settings.solana_rpc_url,
+        settings.solana_rpc_urls,
+    )
+    return {
+        "backend": settings.agent_wallet_backend,
+        "network": settings.solana_network,
+        "rpc_url": rpc_urls[0] if rpc_urls else resolve_solana_rpc_url(settings.solana_network, ""),
+        "rpc_urls": rpc_urls,
+        "auto_create_wallet": settings.solana_auto_create_wallet,
+        "keypair_path": str(path),
+        "sign_only": settings.agent_wallet_sign_only,
+    }

package/agent-wallet/agent_wallet/btc_user_wallets.py

@@ -0,0 +1,217 @@
+"""Host-side helpers for binding local BTC wallets to OpenClaw users."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from agent_wallet.config import resolve_openclaw_home, settings
+from agent_wallet.providers.wdk_btc_local import WdkBtcLocalClient
+from agent_wallet.user_wallets import normalize_user_id
+from agent_wallet.wallet_layer.base import WalletBackendError
+
+
+def _normalize_btc_network(value: str | None) -> str:
+    network = str(value or "").strip().lower()
+    aliases = {"mainnet": "bitcoin"}
+    network = aliases.get(network, network)
+    if network not in {"bitcoin", "testnet", "regtest"}:
+        return "bitcoin"
+    return network
+
+
+def _resolve_service_url(service_url: str | None = None) -> str:
+    effective = (service_url or settings.wdk_btc_service_url).strip()
+    if not effective:
+        raise WalletBackendError("wdk_btc_service_url is required for BTC wallet host operations.")
+    return effective
+
+
+def resolve_user_btc_wallet_path(user_id: str, network: str | None = None) -> Path:
+    effective_network = _normalize_btc_network(network or settings.solana_network)
+    user_dir = resolve_openclaw_home() / "users" / normalize_user_id(user_id) / "wallets"
+    return user_dir / f"btc-{effective_network}-agent.json"
+
+
+def _write_wallet_binding(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+
+
+def get_user_btc_wallet_binding(user_id: str, network: str | None = None) -> dict[str, Any]:
+    path = resolve_user_btc_wallet_path(user_id, network=network)
+    if not path.exists():
+        raise WalletBackendError(f"BTC wallet binding does not exist yet: {path}")
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict) or not str(payload.get("wallet_id") or "").strip():
+        raise WalletBackendError(f"BTC wallet binding is invalid: {path}")
+    return payload
+
+
+def create_user_btc_wallet(
+    user_id: str,
+    *,
+    password: str,
+    label: str | None = None,
+    network: str | None = None,
+    service_url: str | None = None,
+    reveal_seed_phrase: bool = False,
+    account_index: int | None = None,
+) -> dict[str, Any]:
+    effective_network = _normalize_btc_network(network or settings.solana_network)
+    effective_account_index = settings.wdk_btc_account_index if account_index is None else int(account_index)
+    client = WdkBtcLocalClient(_resolve_service_url(service_url))
+    created = client.post_sync(
+        "/v1/btc/wallets/create",
+        {
+            "label": (label or "").strip() or "Agent BTC Wallet",
+            "password": password,
+            "network": effective_network,
+            "revealSeedPhrase": bool(reveal_seed_phrase),
+        },
+    )
+    address = client.post_sync(
+        "/v1/btc/address/resolve",
+        {
+            "walletId": created["walletId"],
+            "accountIndex": effective_account_index,
+            "network": effective_network,
+        },
+    )
+    binding = {
+        "user_id": user_id,
+        "wallet_id": str(created["walletId"]),
+        "label": str(created.get("label") or "Agent BTC Wallet"),
+        "network": effective_network,
+        "account_index": effective_account_index,
+        "address": str(address.get("address") or ""),
+        "storage_format": "local_vault",
+        "service_kind": "wdk-btc-wallet",
+        "created_at": created.get("createdAt"),
+        "updated_at": created.get("updatedAt"),
+    }
+    _write_wallet_binding(resolve_user_btc_wallet_path(user_id, effective_network), binding)
+    return {
+        **binding,
+        "unlocked": bool(created.get("unlocked", True)),
+        "unlock_expires_at": created.get("unlockExpiresAt"),
+        **({"seed_phrase": created["seedPhrase"]} if created.get("seedPhrase") else {}),
+    }
+
+
+def import_user_btc_wallet(
+    user_id: str,
+    *,
+    password: str,
+    seed_phrase: str,
+    label: str | None = None,
+    network: str | None = None,
+    service_url: str | None = None,
+    account_index: int | None = None,
+) -> dict[str, Any]:
+    effective_network = _normalize_btc_network(network or settings.solana_network)
+    effective_account_index = settings.wdk_btc_account_index if account_index is None else int(account_index)
+    client = WdkBtcLocalClient(_resolve_service_url(service_url))
+    created = client.post_sync(
+        "/v1/btc/wallets/import",
+        {
+            "label": (label or "").strip() or "Agent BTC Wallet",
+            "password": password,
+            "seedPhrase": seed_phrase,
+            "network": effective_network,
+        },
+    )
+    address = client.post_sync(
+        "/v1/btc/address/resolve",
+        {
+            "walletId": created["walletId"],
+            "accountIndex": effective_account_index,
+            "network": effective_network,
+        },
+    )
+    binding = {
+        "user_id": user_id,
+        "wallet_id": str(created["walletId"]),
+        "label": str(created.get("label") or "Agent BTC Wallet"),
+        "network": effective_network,
+        "account_index": effective_account_index,
+        "address": str(address.get("address") or ""),
+        "storage_format": "local_vault",
+        "service_kind": "wdk-btc-wallet",
+        "created_at": created.get("createdAt"),
+        "updated_at": created.get("updatedAt"),
+    }
+    _write_wallet_binding(resolve_user_btc_wallet_path(user_id, effective_network), binding)
+    return {
+        **binding,
+        "unlocked": bool(created.get("unlocked", True)),
+        "unlock_expires_at": created.get("unlockExpiresAt"),
+    }
+
+
+def unlock_user_btc_wallet(
+    user_id: str,
+    *,
+    password: str,
+    network: str | None = None,
+    service_url: str | None = None,
+) -> dict[str, Any]:
+    binding = get_user_btc_wallet_binding(user_id, network=network)
+    client = WdkBtcLocalClient(_resolve_service_url(service_url))
+    payload = client.post_sync(
+        "/v1/btc/wallets/unlock",
+        {
+            "walletId": binding["wallet_id"],
+            "password": password,
+            "timeoutSeconds": 0,
+        },
+    )
+    return {
+        **binding,
+        "unlocked": bool(payload.get("unlocked", True)),
+        "unlock_expires_at": payload.get("unlockExpiresAt"),
+    }
+
+
+def reveal_user_btc_wallet_seed_phrase(
+    user_id: str,
+    *,
+    password: str,
+    network: str | None = None,
+    service_url: str | None = None,
+) -> dict[str, Any]:
+    binding = get_user_btc_wallet_binding(user_id, network=network)
+    client = WdkBtcLocalClient(_resolve_service_url(service_url))
+    payload = client.post_sync(
+        "/v1/btc/wallets/reveal-seed",
+        {
+            "walletId": binding["wallet_id"],
+            "password": password,
+        },
+    )
+    return {
+        **binding,
+        "seed_phrase": str(payload.get("seedPhrase") or ""),
+    }
+
+
+def lock_user_btc_wallet(
+    user_id: str,
+    *,
+    network: str | None = None,
+    service_url: str | None = None,
+) -> dict[str, Any]:
+    binding = get_user_btc_wallet_binding(user_id, network=network)
+    client = WdkBtcLocalClient(_resolve_service_url(service_url))
+    payload = client.post_sync(
+        "/v1/btc/wallets/lock",
+        {
+            "walletId": binding["wallet_id"],
+        },
+    )
+    return {
+        **binding,
+        "unlocked": bool(payload.get("unlocked", False)),
+        "unlock_expires_at": None,
+    }