@agentlayer.tech/wallet 0.1.58 → 0.1.65

package/.openclaw/extensions/agent-wallet/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "agent-wallet",
   "name": "Agent Wallet",
   "description": "Official OpenClaw plugin bridge for the agent-wallet backends, including Solana, local BTC, and local EVM.",
-  "version": "0.1.58",
+  "version": "0.1.65",
   "contracts": {
     "tools": [
       "agentlayer_autonomous_approve",

package/.openclaw/extensions/agent-wallet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentlayertech/agent-wallet-plugin",
-  "version": "0.1.58",
+  "version": "0.1.65",
   "description": "OpenClaw plugin bridge for the AgentLayer wallet runtime.",
   "type": "module",
   "license": "SEE LICENSE IN ../../../LICENSE",

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## Unreleased
 
+## v0.1.62 - 2026-07-04
+
+- Made default boot-key storage prompt-free on macOS. The automatic keystore
+  selection no longer probes macOS Keychain because even a read/probe through
+  `/usr/bin/security` can open a GUI password dialog during install or session
+  startup. macOS Keychain remains available only through explicit opt-in with
+  `AGENT_WALLET_KEYSTORE_BACKEND=macos-keychain` (or `native`), while the
+  default path uses the local fallback without showing Keychain prompts.
+  - `agent-wallet/agent_wallet/keystore.py`
+  - `agent-wallet/tests/smoke_keystore.py`
+
+## v0.1.61 - 2026-07-04
+
+- Hardened boot-key installation and migration around desktop keystores:
+  - The npm installer provisions the boot key through the runtime Python
+    keystore bridge instead of unconditionally persisting it in the release
+    `.env`, while keeping a legacy `.env` fallback when no non-interactive
+    keystore round-trip is available.
+  - The Node keystore bridge is bounded by a timeout so a hung Python/keychain
+    operation cannot stall install or reinstall.
+  - macOS keychain writes now run with non-interactive stdin, convert timeouts
+    into failed command results, and make the problematic
+    `set-generic-password-partition-list` ACL update strictly best-effort.
+  - Keystore resolution now verifies that a native backend can read the live
+    boot key or complete a write/read/delete probe before selecting it, falling
+    back cleanly when the OS tool exists but cannot authorize writes.
+  - `agent-wallet/agent_wallet/keystore.py`
+  - `bin/openclaw-agent-wallet.mjs`
+  - `agent-wallet/tests/smoke_keystore.py`
+
 ## v0.1.58 - 2026-07-01
 
 - Resolved SPL token symbol/name in `get_wallet_portfolio` via a batched,

package/README.md

@@ -102,7 +102,7 @@ The CLI uses a versioned runtime layout:
 ~/.openclaw/agent-wallet-runtime/current              # symlink → active release
 ```
 
-On first install, `--yes` generates local runtime secrets. The installer stores `master_key` and `approval_secret` in `~/.openclaw/sealed_keys.json`; only the boot key needed to unlock that sealed bundle is written to the runtime `.env`.
+On first install, `--yes` generates local runtime secrets. The installer stores `master_key` and `approval_secret` in `~/.openclaw/sealed_keys.json`; the boot key needed to unlock that sealed bundle stays in the prompt-free local fallback by default. macOS Keychain is opt-in (`AGENT_WALLET_KEYSTORE_BACKEND=macos-keychain`) because probing it can open a system password dialog during install or startup.
 
 Useful CLI commands (require the global install above):
 

package/VERSION

@@ -1 +1 @@
-0.1.58
+0.1.65

package/agent-wallet/agent_wallet/__init__.py

@@ -2,7 +2,7 @@
 
 # Keep in sync with package.json, pyproject.toml, and the npm installer version.
 # scripts/check_release_version.mjs enforces this on release.
-__version__ = "0.1.58"
+__version__ = "0.1.65"
 
 __all__ = [
     "config",

package/agent-wallet/agent_wallet/boot_key_migration.py

@@ -0,0 +1,158 @@
+"""Transparent, verified migration of the boot key into the OS keystore.
+
+Runs at backend startup. Non-destructive: plaintext is swept ONLY after the
+keystore read-back verifies. Idempotent and best-effort — a partial sweep
+re-runs cleanly next start. See BOOT_KEY_KEYCHAIN_ARCHITECTURE.md.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from agent_wallet.config import (
+    read_boot_key_from_keystore,
+    resolve_openclaw_home,
+    settings,
+)
+from agent_wallet.file_ops import atomic_write_text
+from agent_wallet.keystore import BOOT_KEY_ITEM, PlaintextFileStore, resolve_keystore
+
+_ENV_LINE_PREFIX = "AGENT_WALLET_BOOT_KEY="
+
+
+def _read_legacy_boot_key() -> str:
+    """The authoritative live key from legacy sources only (env override -> file)."""
+    direct = os.getenv("AGENT_WALLET_BOOT_KEY", settings.agent_wallet_boot_key).strip()
+    if direct:
+        return direct
+    key_file = os.getenv("AGENT_WALLET_BOOT_KEY_FILE", settings.agent_wallet_boot_key_file).strip()
+    if key_file:
+        try:
+            return Path(key_file).expanduser().read_text(encoding="utf-8").strip()
+        except OSError:
+            return ""
+    return ""
+
+
+def _env_boot_key_value(line: str) -> str | None:
+    """Return the boot-key value on an AGENT_WALLET_BOOT_KEY= line, else None."""
+    stripped = line.strip()
+    if not stripped.startswith(_ENV_LINE_PREFIX):
+        return None
+    return stripped[len(_ENV_LINE_PREFIX):].strip().strip('"').strip("'")
+
+
+def _strip_boot_key_line(env_path: Path, expected: str) -> bool:
+    """Remove only the AGENT_WALLET_BOOT_KEY line whose value == expected.
+
+    Preserve all other vars, and never strip a line carrying a *different* value
+    (that would signal a key mismatch a human should look at). Returns True if
+    the file changed.
+    """
+    try:
+        lines = env_path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return False
+    kept = [ln for ln in lines if _env_boot_key_value(ln) != expected]
+    if len(kept) == len(lines):
+        return False
+    atomic_write_text(env_path, ("\n".join(kept) + "\n") if kept else "", mode=0o600)
+    return True
+
+
+def _candidate_env_files(runtime: Path) -> list[Path]:
+    """Boot-key .env locations to sweep, deduped.
+
+    Deliberately bounded: a recursive ``**/.env`` walk descends into the hundreds
+    of ``node_modules`` trees under the release dirs and effectively hangs onboarding
+    (observed: 650+ node_modules, glob never returns). The boot key was only ever
+    written to ``releases/<v>/agent-wallet/.env``; ``current``/``previous`` are
+    symlinks into ``releases`` and are resolved to dedupe against their targets.
+    """
+    candidates = list(runtime.glob("releases/*/agent-wallet/.env"))
+    candidates.append(runtime / "current" / "agent-wallet" / ".env")
+    candidates.append(runtime / "previous" / "agent-wallet" / ".env")
+    seen: set[str] = set()
+    out: list[Path] = []
+    for path in candidates:
+        try:
+            key = str(path.resolve())
+        except OSError:
+            key = str(path)
+        if key in seen:
+            continue
+        seen.add(key)
+        if path.exists():
+            out.append(path)
+    return out
+
+
+def _sweep_plaintext(home: Path, expected: str) -> tuple[int, bool]:
+    """Strip matching boot-key lines from every runtime .env; delete the boot-key file.
+
+    Idempotent and value-scoped: only plaintext equal to the authoritative
+    keystore key is removed, so re-running after a fresh installer write (which
+    re-emits the same key) cleans it up on the next start.
+    """
+    runtime = home / "agent-wallet-runtime"
+    swept = 0
+    for env_path in _candidate_env_files(runtime):
+        try:
+            if _strip_boot_key_line(env_path, expected):
+                swept += 1
+        except Exception:
+            continue  # best-effort; re-runs next start
+    removed = False
+    boot_file = runtime / "boot-key"
+    try:
+        if boot_file.read_text(encoding="utf-8").strip() == expected:
+            boot_file.unlink()
+            removed = True
+    except FileNotFoundError:
+        pass
+    except OSError:
+        pass
+    return swept, removed
+
+
+def migrate_boot_key_to_keystore() -> dict:
+    """Move a legacy plaintext boot key into the keystore, verify, then sweep plaintext.
+
+    Runs on every startup (guarded once per process). When the keystore already
+    holds the key, it still re-sweeps any plaintext an installer re-emitted, so a
+    per-release .env write never re-establishes a permanent leak.
+    """
+    store = resolve_keystore()
+    home = resolve_openclaw_home()
+
+    # Do not sweep into a plaintext fallback: that offers no at-rest improvement,
+    # and the user explicitly chose to stay on the current file in that case.
+    if isinstance(store, PlaintextFileStore):
+        return {"migrated": False, "backend": store.backend_id, "swept_env_files": 0,
+                "removed_boot_key_file": False, "reason": "no-os-keystore"}
+
+    authoritative = read_boot_key_from_keystore()
+    first_time = False
+    if not authoritative:
+        legacy_key = _read_legacy_boot_key()
+        if not legacy_key:
+            return {"migrated": False, "backend": store.backend_id, "swept_env_files": 0,
+                    "removed_boot_key_file": False, "reason": "no-legacy-key"}
+        try:
+            store.set(BOOT_KEY_ITEM, legacy_key)
+        except Exception as exc:
+            return {"migrated": False, "backend": store.backend_id, "swept_env_files": 0,
+                    "removed_boot_key_file": False, "reason": f"keystore-set-failed: {exc}"}
+        # Verify-before-delete.
+        if read_boot_key_from_keystore() != legacy_key:
+            return {"migrated": False, "backend": store.backend_id, "swept_env_files": 0,
+                    "removed_boot_key_file": False, "reason": "verify-failed"}
+        authoritative = legacy_key
+        first_time = True
+
+    swept, removed = _sweep_plaintext(home, authoritative)
+    migrated = first_time or swept > 0 or removed
+    return {"migrated": migrated, "backend": store.backend_id, "swept_env_files": swept,
+            "removed_boot_key_file": removed,
+            "reason": "ok" if migrated else "already-clean"}

package/agent-wallet/agent_wallet/boot_key_recovery.py

@@ -0,0 +1,46 @@
+"""User-facing boot-key export/import for paper backup and machine recovery.
+
+The boot key is a retrievable string (baseline A), so recovery is simple: show
+it for a paper backup, or write a recorded value back into the keystore on a new
+machine. Full recovery kit = boot key + the already-encrypted sealed_keys.json +
+wallet files. See BOOT_KEY_KEYCHAIN_ARCHITECTURE.md.
+"""
+
+from __future__ import annotations
+
+from agent_wallet.config import read_boot_key_from_keystore, resolve_boot_key
+from agent_wallet.keystore import BOOT_KEY_ITEM, resolve_keystore
+from agent_wallet.wallet_layer.base import WalletBackendError
+
+_EXPORT_WARNING = (
+    "SENSITIVE: anyone with this boot key AND your ~/.openclaw encrypted files "
+    "controls every wallet (Solana/EVM/BTC). Write it down and store it offline."
+)
+
+
+def export_boot_key() -> str:
+    """Return the live boot key. Raises if none is resolvable."""
+    key = resolve_boot_key()
+    if not key:
+        raise WalletBackendError(
+            "No boot key is available to export. The wallet is not set up on this machine."
+        )
+    return key
+
+
+def import_boot_key(value: str) -> dict:
+    """Write a recorded boot key into the OS keystore and verify the read-back."""
+    key = str(value or "").strip()
+    if not key:
+        raise WalletBackendError("A non-empty boot key is required for import.")
+    store = resolve_keystore()
+    store.set(BOOT_KEY_ITEM, key)
+    if read_boot_key_from_keystore() != key:
+        raise WalletBackendError(
+            f"Boot key import could not be verified from the {store.backend_id} keystore."
+        )
+    return {"imported": True, "backend": store.backend_id}
+
+
+def export_warning() -> str:
+    return _EXPORT_WARNING

package/agent-wallet/agent_wallet/config.py

@@ -80,6 +80,7 @@ def reload_settings() -> Settings:
     refreshed = Settings()
     for field_name in Settings.model_fields:
         setattr(settings, field_name, getattr(refreshed, field_name))
+    clear_secret_caches()
     return settings
 
 
@@ -385,11 +386,72 @@ def _env_bool(name: str, default: bool) -> bool:
     return raw.strip().lower() in {"1", "true", "yes", "on"}
 
 
+def envelope_kdf_migration_enabled() -> bool:
+    """Whether argon2id envelopes are lazily rewritten to hkdf-sha256 after a
+    successful decrypt. Disable with AGENT_WALLET_ENVELOPE_KDF_MIGRATION=0
+    (e.g. when a rollback to a pre-hkdf runtime must stay possible)."""
+    return _env_bool("AGENT_WALLET_ENVELOPE_KDF_MIGRATION", True)
+
+
+_boot_key_keystore_cache: dict[str, str] = {}
+
+
+def clear_secret_caches() -> None:
+    """Reset all process-local secret-resolution caches.
+
+    Covers the memoized keystore backend, the boot key read from the OS
+    keystore, unsealed secrets, and derived envelope keys. Wired into
+    ``reload_settings`` so config reloads always observe fresh state; call it
+    directly in tests that rotate keystore contents in-process.
+    """
+    _boot_key_keystore_cache.clear()
+    from agent_wallet.keystore import clear_keystore_cache
+
+    clear_keystore_cache()
+    from agent_wallet.sealed_keys import clear_unseal_cache
+
+    clear_unseal_cache()
+    from agent_wallet.encrypted_storage import clear_derived_key_cache
+
+    clear_derived_key_cache()
+
+
+def read_boot_key_from_keystore() -> str:
+    """Read the boot key from the OS keystore. Never raises; '' on any failure.
+
+    Successful (non-empty) reads are memoized per keystore service for the
+    process lifetime — every uncached read costs a subprocess call.
+    """
+    try:
+        from agent_wallet.keystore import BOOT_KEY_ITEM, resolve_keystore
+
+        service_key = os.getenv("AGENT_WALLET_KEYSTORE_SERVICE", "").strip()
+        cached = _boot_key_keystore_cache.get(service_key)
+        if cached:
+            return cached
+        value = resolve_keystore().get(BOOT_KEY_ITEM)
+        text = value.strip() if isinstance(value, str) else ""
+        if text:
+            _boot_key_keystore_cache[service_key] = text
+        return text
+    except Exception:
+        return ""
+
+
 def resolve_boot_key() -> str:
-    """Resolve the boot key used to unlock sealed secrets from disk."""
+    """Resolve the boot key used to unlock sealed secrets from disk.
+
+    Precedence (superset of the legacy lookup, so existing installs keep working):
+      1. AGENT_WALLET_BOOT_KEY env / settings override
+      2. OS keystore (the hardened path)
+      3. AGENT_WALLET_BOOT_KEY_FILE / boot-key file (legacy)
+    """
     direct = os.getenv("AGENT_WALLET_BOOT_KEY", settings.agent_wallet_boot_key).strip()
     if direct:
         return direct
+    from_keystore = read_boot_key_from_keystore()
+    if from_keystore:
+        return from_keystore
     key_file = os.getenv("AGENT_WALLET_BOOT_KEY_FILE", settings.agent_wallet_boot_key_file).strip()
     if not key_file:
         return ""

package/agent-wallet/agent_wallet/encrypted_storage.py

@@ -6,6 +6,7 @@ import base64
 import hashlib
 import hmac
 import json
+import os
 from pathlib import Path
 from typing import Any
 
@@ -17,6 +18,10 @@ ENCRYPTED_WALLET_KIND = "openclaw-agent-wallet-secret"
 ENCRYPTED_WALLET_VERSION = 1
 USER_SCOPED_KEY_SALT = b"openclaw-agent-wallet-user-key-v1"
 
+KDF_ARGON2ID = "argon2id"
+KDF_HKDF_SHA256 = "hkdf-sha256"
+_HKDF_INFO = b"openclaw-agent-wallet-envelope-hkdf-v1"
+
 
 def _load_secretbox():
     try:
@@ -28,11 +33,19 @@ def _load_secretbox():
     return pwhash, secret, utils
 
 
-def _derive_key(master_key: str, salt: bytes) -> bytes:
-    if not master_key.strip():
-        raise WalletBackendError(
-            "Encrypted wallet storage requires AGENT_WALLET_BOOT_KEY and a sealed master_key."
-        )
+# Derived envelope keys are expensive (argon2id ~1s each), so cache them by
+# (kdf, master_key, salt). In-memory only, never serialized; bounded so a
+# pathological caller cannot grow it without limit.
+_derived_key_cache: dict[tuple[str, str, bytes], bytes] = {}
+_DERIVED_KEY_CACHE_MAX = 64
+
+
+def clear_derived_key_cache() -> None:
+    """Drop cached derived keys (wired into config.clear_secret_caches)."""
+    _derived_key_cache.clear()
+
+
+def _kdf_argon2id(master_key: str, salt: bytes) -> bytes:
     pwhash, secret, _ = _load_secretbox()
     return pwhash.argon2id.kdf(
         secret.SecretBox.KEY_SIZE,
@@ -43,6 +56,52 @@ def _derive_key(master_key: str, salt: bytes) -> bytes:
     )
 
 
+def _kdf_hkdf_sha256(master_key: str, salt: bytes) -> bytes:
+    # RFC 5869 extract+expand, one 32-byte block. Only safe because every
+    # caller passes machine-generated high-entropy key material (boot key /
+    # sealed master key) — password-hardness is what argon2id was paying for,
+    # and user passwords never reach this module.
+    prk = hmac.new(salt, master_key.encode("utf-8"), hashlib.sha256).digest()
+    return hmac.new(prk, _HKDF_INFO + b"\x01", hashlib.sha256).digest()
+
+
+def _default_write_kdf() -> str:
+    raw = os.getenv("AGENT_WALLET_ENVELOPE_KDF", "").strip().lower()
+    return KDF_ARGON2ID if raw == KDF_ARGON2ID else KDF_HKDF_SHA256
+
+
+def envelope_kdf(raw_text: str) -> str:
+    """Return the kdf recorded in an encrypted envelope ('' when not one)."""
+    try:
+        payload = json.loads(raw_text)
+    except json.JSONDecodeError:
+        return ""
+    if not isinstance(payload, dict) or payload.get("kind") != ENCRYPTED_WALLET_KIND:
+        return ""
+    return str(payload.get("kdf") or KDF_ARGON2ID)
+
+
+def _derive_key(master_key: str, salt: bytes, *, kdf: str = KDF_ARGON2ID) -> bytes:
+    if not master_key.strip():
+        raise WalletBackendError(
+            "Encrypted wallet storage requires AGENT_WALLET_BOOT_KEY and a sealed master_key."
+        )
+    if kdf == KDF_HKDF_SHA256:
+        # Cheap enough to skip the cache entirely.
+        return _kdf_hkdf_sha256(master_key, bytes(salt))
+    if kdf != KDF_ARGON2ID:
+        raise WalletBackendError(f"Encrypted wallet file uses an unsupported kdf: {kdf}")
+    cache_key = (kdf, master_key, bytes(salt))
+    cached = _derived_key_cache.get(cache_key)
+    if cached is not None:
+        return cached
+    key = _kdf_argon2id(master_key, salt)
+    if len(_derived_key_cache) >= _DERIVED_KEY_CACHE_MAX:
+        _derived_key_cache.clear()
+    _derived_key_cache[cache_key] = key
+    return key
+
+
 def _derive_user_scoped_key(
     master_key: str,
     *,
@@ -79,19 +138,27 @@ def encrypt_secret_material(
     *,
     master_key: str | None = None,
     metadata: dict[str, Any] | None = None,
+    kdf: str | None = None,
 ) -> str:
-    """Encrypt wallet secret material into a JSON envelope."""
+    """Encrypt wallet secret material into a JSON envelope.
+
+    ``kdf`` selects the key derivation for this envelope; None resolves the
+    process default (hkdf-sha256 unless AGENT_WALLET_ENVELOPE_KDF=argon2id).
+    """
+    effective_kdf = kdf if kdf is not None else _default_write_kdf()
+    if effective_kdf not in {KDF_ARGON2ID, KDF_HKDF_SHA256}:
+        raise WalletBackendError(f"Unsupported envelope kdf: {effective_kdf}")
     _, secret, utils = _load_secretbox()
     effective_master_key = master_key if master_key is not None else resolve_wallet_master_key()
     salt = utils.random(16)
-    key = _derive_key(effective_master_key, salt)
+    key = _derive_key(effective_master_key, salt, kdf=effective_kdf)
     box = secret.SecretBox(key)
     encrypted = box.encrypt(secret_material.encode("utf-8"))
     payload: dict[str, Any] = {
         "kind": ENCRYPTED_WALLET_KIND,
         "version": ENCRYPTED_WALLET_VERSION,
         "cipher": "secretbox",
-        "kdf": "argon2id",
+        "kdf": effective_kdf,
         "salt_b64": base64.b64encode(salt).decode("ascii"),
         "nonce_b64": base64.b64encode(encrypted.nonce).decode("ascii"),
         "ciphertext_b64": base64.b64encode(encrypted.ciphertext).decode("ascii"),
@@ -124,7 +191,8 @@ def decrypt_secret_material(
         raise WalletBackendError("Encrypted wallet file is malformed.") from exc
 
     effective_master_key = master_key if master_key is not None else resolve_wallet_master_key()
-    key = _derive_key(effective_master_key, salt)
+    kdf = str(payload.get("kdf") or KDF_ARGON2ID)
+    key = _derive_key(effective_master_key, salt, kdf=kdf)
     box = secret.SecretBox(key)
     try:
         plaintext = box.decrypt(ciphertext, nonce)