karma-openclaw 0.4.0__py3-none-any.whl

karma_openclaw/__init__.py

@@ -0,0 +1,21 @@
+"""Karma ↔ OpenClaw MCP bridge package.
+
+Keep package import light: handoff/helpers must work without pulling FastMCP
+(mcp v1). Server entrypoints are exported lazily.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["build_app", "main"]
+
+__version__ = "0.4.0"
+
+
+def __getattr__(name: str) -> Any:
+    if name in ("build_app", "main"):
+        from karma_openclaw.server import build_app, main
+
+        return build_app if name == "build_app" else main
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

karma_openclaw/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m karma_openclaw``."""
+
+from karma_openclaw.server import main
+
+if __name__ == "__main__":
+    main()

karma_openclaw/agent_binding.py

@@ -0,0 +1,180 @@
+"""Agent-side Runtime Key binding: the Ed25519 key + the per-request signature.
+
+Why this exists. A Runtime Key is a bearer token: whoever holds ``KRM_RT_...`` can spend
+the owner's money within its limits. Karma therefore refuses to serve *any* key that is
+not bound to an agent public key and activated by the owner with the 8-character
+matching code. So an agent process must be able to
+
+  (a) present its Ed25519 public key (``POST /runtime/bind-key``), and
+  (b) sign every ``/runtime/*`` request (``X-Karma-Agent-Signature`` + timestamp + nonce).
+
+This mirrors ``sdk/runtime_client.py`` and, on the server side,
+``services/runtime_wallet.build_agent_request_message``. Both sides are pinned against
+each other by tests so the format cannot drift.
+
+Env:
+  KARMA_AGENT_PRIVATE_KEY  base64(32 raw bytes) or 64-char hex -- never leaves this process
+  KARMA_AGENT_ID           the agent id the owner authorized (falls back to what the key was minted for)
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+import uuid
+from datetime import UTC, datetime, timezone
+from typing import Any
+
+
+def runtime_key_id(token: str) -> str:
+    """Pull the key_id out of ``KRM_RT_<key_id>_<secret>`` (the signature message needs it)."""
+    raw = (token or "").strip()
+    if not raw.startswith("KRM_RT_"):
+        return ""
+    head, _, _ = raw[len("KRM_RT_") :].partition("_")
+    return head
+
+
+def agent_key_from_seed(seed: str):
+    """base64(raw 32 bytes) or 64-char hex -> Ed25519PrivateKey."""
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+    text = (seed or "").strip()
+    if not text:
+        raise ValueError("agent private key is empty")
+    if len(text) == 64 and all(c in "0123456789abcdefABCDEF" for c in text):
+        raw = bytes.fromhex(text)
+    else:
+        raw = base64.b64decode(text, validate=True)
+    if len(raw) != 32:
+        raise ValueError("agent private key must be 32 raw bytes (base64 or hex seed)")
+    return Ed25519PrivateKey.from_private_bytes(raw)
+
+
+def agent_key_from_env() -> Any | None:
+    """The agent's Ed25519 key, or None when no seed is configured.
+
+    Reads the env var first, then the on-disk credential file -- the same file
+    ``karma_connect_claim`` writes, so a freshly paired process can sign without
+    waiting for its host to restart it.
+    """
+    from karma_openclaw.agent_env import credential
+
+    seed = credential("KARMA_AGENT_PRIVATE_KEY")
+    if not seed:
+        return None
+    return agent_key_from_seed(seed)
+
+
+def ensure_local_agent_key() -> Any | None:
+    """本机 agent 私钥：有就用，没有就现生成一把并落盘（0600）。
+
+    为什么由 agent 自己生成：这把私钥是「光有钥匙字符串花不了钱」的全部依据，
+    它必须只存在于 agent 本机 —— Karma 服务端从头到尾看不到它，只收到公钥，
+    用来把 Runtime Key 钉在这次的 agent 身上。
+    """
+    existing = agent_key_from_env()
+    if existing is not None:
+        return existing
+    try:
+        import base64 as _b64
+
+        from cryptography.hazmat.primitives import serialization
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+        from karma_openclaw.agent_env import upsert_credential
+
+        key = Ed25519PrivateKey.generate()
+        raw = key.private_bytes(
+            serialization.Encoding.Raw,
+            serialization.PrivateFormat.Raw,
+            serialization.NoEncryption(),
+        )
+        upsert_credential("KARMA_AGENT_PRIVATE_KEY", _b64.b64encode(raw).decode())
+        return key
+    except Exception:  # noqa: BLE001 - 落不了盘就当没有，退回「领取时再绑」那条老路
+        return None
+
+
+def agent_id_from_env() -> str:
+    from karma_openclaw.agent_env import credential
+
+    return credential("KARMA_AGENT_ID")
+
+
+def agent_public_key_b64(key: Any) -> str:
+    """Ed25519 public key as base64 of the raw 32 bytes -- the shape the server stores."""
+    from cryptography.hazmat.primitives import serialization
+
+    raw = key.public_key().public_bytes(
+        serialization.Encoding.Raw, serialization.PublicFormat.Raw
+    )
+    return base64.b64encode(raw).decode()
+
+
+def build_agent_request_message(
+    *, key_id: str, method: str, path: str, timestamp: str, nonce: str, body_sha256: str
+) -> str:
+    """The exact text the server recomputes. Do not reorder these lines."""
+    return "\n".join(
+        [
+            "Karma Runtime Request",
+            "key_id:" + key_id,
+            "method:" + method.upper(),
+            "path:" + path,
+            "timestamp:" + timestamp,
+            "nonce:" + nonce,
+            "body_sha256:" + body_sha256,
+        ]
+    )
+
+
+def build_agent_pairing_request_message(
+    *, agent_name: str, public_key: str, nonce: str, timestamp: str
+) -> str:
+    """与 services/runtime_wallet.build_agent_pairing_request_message 逐字一致。"""
+    return "\n".join(
+        [
+            "Karma Agent Pairing Request",
+            "agent_name:" + agent_name,
+            "public_key:" + public_key,
+            "nonce:" + nonce,
+            "timestamp:" + timestamp,
+        ]
+    )
+
+
+def sign_pairing_request(*, key: Any, agent_name: str, public_key: str) -> dict[str, str]:
+    """申请接入要带的三件套：证明申请方真的持有这把公钥对应的私钥。"""
+    timestamp = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+    nonce = uuid.uuid4().hex
+    message = build_agent_pairing_request_message(
+        agent_name=agent_name, public_key=public_key, nonce=nonce, timestamp=timestamp
+    )
+    return {
+        "signature": base64.b64encode(key.sign(message.encode("utf-8"))).decode(),
+        "nonce": nonce,
+        "timestamp": timestamp,
+    }
+
+
+def sign_runtime_request(
+    *, key: Any, key_id: str, method: str, path: str, body: bytes
+) -> dict[str, str]:
+    """The three headers a bound key has to carry on every request."""
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    nonce = uuid.uuid4().hex
+    message = build_agent_request_message(
+        key_id=key_id,
+        method=method,
+        path=path,
+        timestamp=timestamp,
+        nonce=nonce,
+        body_sha256=hashlib.sha256(body or b"").hexdigest(),
+    )
+    signature = base64.b64encode(key.sign(message.encode("utf-8"))).decode()
+    return {
+        "X-Karma-Agent-Signature": signature,
+        "X-Karma-Runtime-Timestamp": timestamp,
+        "X-Karma-Runtime-Nonce": nonce,
+    }

karma_openclaw/agent_env.py

@@ -0,0 +1,121 @@
+# -*- coding: utf-8 -*-
+"""凭据落在哪、以及怎么把它读回来。
+
+`karma_connect_claim` 把凭据写到 ``~/.karma/agent.env``（0600）。但在此之前没有任何
+代码会把它读回 ``os.environ`` —— 也就是说：**已经跑着的 MCP 进程永远看不到刚领到的
+凭据**，非要宿主把 MCP server 重启一次才生效。而「宿主重启」恰恰是我们不能假设用户
+做得到的那一步（OpenClaw 的 config 重载链路本身就可能坏着）。
+
+所以路径解析放在这一个模块里，写盘和读盘共用；HTTP 层每次要用凭据时按文件
+mtime+size 判断是否需要重读，文件变了就立刻生效。
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+#: 这两把钥匙在 agent 侧的用途不同：API key 调公共 API，Runtime key 调 /runtime/*。
+CREDENTIAL_KEYS = (
+    "KARMA_API_KEY",
+    "KARMA_RUNTIME_KEY",
+    "KARMA_RUNTIME_URL",
+    "KARMA_AGENT_ID",
+    "KARMA_AGENT_PRIVATE_KEY",
+)
+
+
+def agent_env_path() -> Path:
+    """凭据文件位置：``KARMA_AGENT_ENV_PATH`` 覆盖，否则 ``~/.karma/agent.env``。"""
+    override = os.environ.get("KARMA_AGENT_ENV_PATH", "").strip()
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".karma" / "agent.env"
+
+
+def read_agent_env() -> dict:
+    """把文件解析成 dict；文件不存在或读不动时返回空 dict（不抛）。"""
+    path = agent_env_path()
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    values: dict = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        if key:
+            values[key] = value.strip()
+    return values
+
+
+_cache: dict = {"stamp": None, "values": {}}
+
+
+def _stamp():
+    path = agent_env_path()
+    try:
+        st = path.stat()
+    except OSError:
+        return (str(path), None, None)
+    return (str(path), st.st_mtime_ns, st.st_size)
+
+
+def load_agent_env(force: bool = False) -> dict:
+    """磁盘上的凭据；文件变了就重读，没变就吃缓存（每次工具调用都会走这里）。"""
+    stamp = _stamp()
+    if force or _cache["stamp"] != stamp:
+        _cache["stamp"] = stamp
+        _cache["values"] = read_agent_env()
+    return _cache["values"]
+
+
+def invalidate_agent_env() -> None:
+    """刚写完文件时调用，避免同一进程里还吃旧缓存。"""
+    _cache["stamp"] = None
+    load_agent_env(force=True)
+
+
+def upsert_credential(name: str, value: str) -> Path:
+    """把一对键值并进凭据文件（0600），同名行就地替换。
+
+    agent 自己的 Ed25519 私钥要先落盘再上报：进程崩了、宿主重启了，它还得在。
+    """
+    path = agent_env_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        lines = []
+    prefix = name + "="
+    out: list = []
+    replaced = False
+    for line in lines:
+        if line.strip().startswith(prefix):
+            if not replaced:
+                out.append(prefix + value)
+                replaced = True
+            continue
+        out.append(line)
+    if not replaced:
+        out.append(prefix + value)
+    text = "\n".join(out).rstrip("\n") + "\n"
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(text, encoding="utf-8")
+    try:
+        os.chmod(tmp, 0o600)
+    except OSError:
+        pass
+    os.replace(tmp, path)
+    invalidate_agent_env()
+    return path
+
+
+def credential(name: str) -> str:
+    """环境变量优先（宿主显式注入的压过文件），否则回落到凭据文件。"""
+    value = (os.environ.get(name) or "").strip()
+    if value:
+        return value
+    return str(load_agent_env().get(name) or "").strip()

karma_openclaw/bilateral_tools.py

@@ -0,0 +1,104 @@
+"""KarmaBilateral MCP tools for OpenClaw — lock/bind/settle via BFF API."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.parse import quote
+
+from karma_openclaw.http_client import api_get, api_post
+
+
+def register_bilateral_tools(mcp):
+    """Register KarmaBilateral tools on the MCP server."""
+
+    @mcp.tool()
+    async def karma_bilateral_lock(token: str, amount: str, role: str = "buyer") -> dict[str, Any]:
+        """Lock USDC into KarmaBilateral and mint a Bill Token.
+
+        Both buyer AND agent must call this before any task begins.
+        This replaces the old lockFunds flow.
+
+        Args:
+            token: ERC-20 token address (use USDC address for testnet)
+            amount: Amount in base units, e.g. '10000000' for 10 USDC
+            role: 'buyer' or 'agent'
+        """
+        return await api_post("/v1/bilateral/lock", {
+            "token": token,
+            "amount": int(amount),
+            "role": role,
+        })
+
+    @mcp.tool()
+    async def karma_bilateral_bind(buyer_bill_id: int, agent_bill_id: int, scope_description: str) -> dict[str, Any]:
+        """Bilaterally bind buyer + agent Bill Tokens. Both sides freeze.
+
+        Must be called AFTER both parties have locked (karma_bilateral_lock).
+        This enters the BOUND state — bills cannot be withdrawn until settled.
+
+        Args:
+            buyer_bill_id: The bill ID from buyer's lock call
+            agent_bill_id: The bill ID from agent's lock call
+            scope_description: Human-readable task scope, e.g. 'search:latest-pricing'
+        """
+        import hashlib
+        scope_hash = "0x" + hashlib.sha256(scope_description.encode()).hexdigest()
+        return await api_post("/v1/bilateral/bind", {
+            "buyer_bill_id": buyer_bill_id,
+            "agent_bill_id": agent_bill_id,
+            "scope_hash": scope_hash,
+        })
+
+    @mcp.tool()
+    async def karma_bilateral_settle(binding_id: int, proof_description: str) -> dict[str, Any]:
+        """Submit settlement proof for a binding. Enters FINALIZING state.
+
+        After the settle delay and dispute window pass, call
+        karma_bilateral_finalize to complete settlement.
+
+        Args:
+            binding_id: The binding ID from the bind call
+            proof_description: What was delivered, e.g. 'ipfs://Qm...evidence'
+        """
+        import hashlib
+        proof_hash = "0x" + hashlib.sha256(proof_description.encode()).hexdigest()
+        return await api_post("/v1/bilateral/settle", {
+            "binding_id": binding_id,
+            "proof_hash": proof_hash,
+        })
+
+    @mcp.tool()
+    async def karma_bilateral_finalize(binding_id: int) -> dict[str, Any]:
+        """Finalize settlement after dispute window closes. Burns bills, releases USDC.
+
+        Can only be called after the dispute window has passed since settle().
+        """
+        return await api_post(f"/v1/bilateral/finalize/{binding_id}", {})
+
+    @mcp.tool()
+    async def karma_bilateral_status(binding_id: int) -> dict[str, Any]:
+        """Query the full status of a binding — state, bill states, USDC locked.
+
+        Returns:
+            binding_id, state, bill_states (list), can_settle, can_dispute,
+            can_finalize, usdc_locked, settle_after
+        """
+        return await api_get(f"/v1/bilateral/status/{binding_id}")
+
+    @mcp.tool()
+    async def karma_bilateral_dispute(binding_id: int, reason: str) -> dict[str, Any]:
+        """Raise a dispute on a binding in FINALIZING state.
+
+        Only the buyer can dispute. Must be within the dispute window.
+
+        Args:
+            binding_id: The binding to dispute
+            reason: Human-readable reason for dispute
+        """
+        import hashlib
+        evidence_hash = "0x" + hashlib.sha256(reason.encode()).hexdigest()
+        # Dispute via direct contract call through BFF
+        return await api_post(f"/v1/bilateral/dispute/{binding_id}", {
+            "evidence_hash": evidence_hash,
+        })

karma_openclaw/guard.py

@@ -0,0 +1,152 @@
+"""Handoff and policy gates before OpenClaw mutates Karma state."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from karma_openclaw.handoff import validate_handoff_v1
+
+
+def _env_flag(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() in ("1", "true", "yes")
+
+
+def buyer_confirm_allowed() -> bool:
+    return _env_flag("KARMA_OPENCLAW_ALLOW_BUYER_CONFIRM")
+
+
+def buyer_accept_allowed() -> bool:
+    return _env_flag("KARMA_OPENCLAW_ALLOW_BUYER_ACCEPT")
+
+
+def setup_mutations_allowed() -> bool:
+    """Contract / settlement create — default off (Console)."""
+    return _env_flag("KARMA_OPENCLAW_ALLOW_SETUP_MUTATIONS")
+
+
+def load_handoff_payload(handoff_json: str | None) -> dict[str, Any]:
+    raw = (handoff_json or "").strip()
+    if not raw:
+        path = os.environ.get("KARMA_OPENCLAW_HANDOFF_PATH", "").strip()
+        if path:
+            raw = Path(path).read_text(encoding="utf-8").strip()
+    if not raw:
+        raise ValueError(
+            "handoff JSON required: pass handoff_json or set KARMA_OPENCLAW_HANDOFF_PATH to a handoff v1 file"
+        )
+    payload = json.loads(raw)
+    if not isinstance(payload, dict):
+        raise ValueError("handoff must be a JSON object")
+    return payload
+
+
+def require_valid_handoff(handoff_json: str | None) -> tuple[dict[str, Any] | None, dict[str, Any]]:
+    """
+    Returns (error_dict, normalized_handoff).
+
+    error_dict is None when handoff validates locally.
+    """
+    try:
+        payload = load_handoff_payload(handoff_json)
+    except (ValueError, json.JSONDecodeError) as exc:
+        return (
+            {
+                "ok": False,
+                "error": "handoff_required",
+                "detail": str(exc),
+                "hint": "Complete Console authorization first; see karma_manual_auth_checklist",
+            },
+            {},
+        )
+
+    ok, errors, normalized = validate_handoff_v1(payload)
+    if not ok:
+        return (
+            {
+                "ok": False,
+                "error": "handoff_invalid",
+                "errors": errors,
+                "hint": "Fix handoff.json manual_console_steps_completed after Console steps",
+            },
+            normalized,
+        )
+    return None, normalized
+
+
+def block_response(reason: str, *, hint: str = "") -> dict[str, Any]:
+    out: dict[str, Any] = {"ok": False, "error": reason}
+    if hint:
+        out["hint"] = hint
+    return out
+
+
+def server_attestation_required() -> bool:
+    return _env_flag("KARMA_OPENCLAW_REQUIRE_SERVER_ATTESTATION")
+
+
+async def require_valid_handoff_for_automation(
+    handoff_json: str | None,
+    *,
+    karma_identity_id: str | None = None,
+) -> tuple[dict[str, Any] | None, dict[str, Any]]:
+    """
+    Local handoff validation plus optional server attestation (POST handoff-confirm).
+    """
+    err, normalized = require_valid_handoff(handoff_json)
+    if err:
+        return err, normalized
+
+    if not server_attestation_required():
+        return None, normalized
+
+    task_id = str(normalized.get("task_id") or "").strip()
+    kid = (
+        (karma_identity_id or "").strip()
+        or os.environ.get("KARMA_ID", "").strip()
+        or str(normalized.get("buyer_identity_id") or "").strip()
+    )
+    if not task_id or not kid:
+        return (
+            {
+                "ok": False,
+                "error": "attestation_context_missing",
+                "detail": "task_id and karma_identity_id required for server attestation check",
+                "hint": "Set KARMA_ID to this OpenClaw party identity",
+            },
+            normalized,
+        )
+
+    from urllib.parse import quote
+
+    from karma_openclaw.http_client import api_get
+
+    try:
+        path = (
+            f"/v1/openclaw/handoff-attestation?task_id={quote(task_id, safe='')}"
+            f"&karma_identity_id={quote(kid, safe='')}"
+        )
+        att = await api_get(path)
+    except Exception as exc:  # noqa: BLE001
+        return (
+            {
+                "ok": False,
+                "error": "attestation_check_failed",
+                "detail": str(exc),
+                "hint": "Call POST /v1/openclaw/handoff-confirm in Console first",
+            },
+            normalized,
+        )
+
+    if not (isinstance(att, dict) and att.get("attested")):
+        return (
+            {
+                "ok": False,
+                "error": "handoff_not_attested",
+                "hint": "Complete Console: automation-readiness → handoff-confirm → export handoff",
+            },
+            normalized,
+        )
+    return None, normalized

karma_openclaw/handoff.py

@@ -0,0 +1,102 @@
+"""OpenClaw ↔ OpenClaw task handoff (v1) — coordination without automating authorization."""
+
+from __future__ import annotations
+
+from typing import Any
+
+HANDOFF_VERSION = "1"
+
+# Steps that MUST be completed by a human in Karma Console (or wallet UI), not by Claw MCP.
+MANUAL_CONSOLE_STEPS_BUYER = frozenset(
+    {
+        "buyer_create_voucher",
+        "buyer_mint_runtime_key",
+        "buyer_lock_capacity",
+    }
+)
+MANUAL_CONSOLE_STEPS_SELLER = frozenset(
+    {
+        "seller_accept_voucher",
+        "seller_mint_runtime_key",
+        "seller_lock_capacity",
+    }
+)
+MANUAL_CONSOLE_STEPS_SHARED = frozenset(
+    {
+        "settlement_created",
+        "settlement_worker_locked",
+    }
+)
+
+ALL_KNOWN_MANUAL_STEPS = MANUAL_CONSOLE_STEPS_BUYER | MANUAL_CONSOLE_STEPS_SELLER | MANUAL_CONSOLE_STEPS_SHARED
+
+
+def validate_handoff_v1(payload: dict[str, Any]) -> tuple[bool, list[str], dict[str, Any]]:
+    """
+    Validate handoff JSON shape and return (ok, error_messages, normalized_view).
+
+    Does not call Karma HTTP — use together with ``karma_validate_handoff`` MCP tool for live checks.
+    """
+    errors: list[str] = []
+    if payload.get("handoff_version") != HANDOFF_VERSION:
+        errors.append(f"handoff_version must be {HANDOFF_VERSION!r}")
+
+    for field in ("trace_id", "task_id", "buyer_identity_id", "seller_identity_id"):
+        val = payload.get(field)
+        if not isinstance(val, str) or not val.strip():
+            errors.append(f"{field} is required (non-empty string)")
+
+    voucher_id = payload.get("voucher_id")
+    if voucher_id is not None and (not isinstance(voucher_id, str) or not voucher_id.strip()):
+        errors.append("voucher_id must be a non-empty string when present")
+
+    auth = payload.get("authorization")
+    if not isinstance(auth, dict):
+        errors.append("authorization object is required")
+        auth = {}
+
+    completed = auth.get("manual_console_steps_completed")
+    if not isinstance(completed, list):
+        errors.append("authorization.manual_console_steps_completed must be a list of step ids")
+        completed = []
+
+    unknown = [s for s in completed if s not in ALL_KNOWN_MANUAL_STEPS]
+    if unknown:
+        errors.append(f"unknown manual_console_steps_completed entries: {unknown}")
+
+    # Minimum bar before Claw may run verify / delivery automation.
+    required_before_automation = {"buyer_create_voucher", "seller_accept_voucher", "settlement_created"}
+    missing = sorted(required_before_automation - set(completed))
+    if missing:
+        errors.append(
+            "authorization incomplete for automated verify/delivery — complete in Console first, "
+            f"then add to manual_console_steps_completed: {missing}"
+        )
+
+    voucher_status = auth.get("voucher_status")
+    if voucher_status is not None and voucher_status not in (
+        "created",
+        "accepted",
+        "used",
+        "cancelled",
+        "expired",
+    ):
+        errors.append(f"authorization.voucher_status invalid: {voucher_status!r}")
+
+    if voucher_status and voucher_status != "accepted" and "seller_accept_voucher" in completed:
+        errors.append("voucher_status must be 'accepted' when seller_accept_voucher is marked complete")
+
+    normalized = {
+        "handoff_version": HANDOFF_VERSION,
+        "trace_id": str(payload.get("trace_id", "")).strip(),
+        "task_id": str(payload.get("task_id", "")).strip(),
+        "voucher_id": str(voucher_id).strip() if voucher_id else None,
+        "buyer_identity_id": str(payload.get("buyer_identity_id", "")).strip(),
+        "seller_identity_id": str(payload.get("seller_identity_id", "")).strip(),
+        "bill_credit_amount": payload.get("bill_credit_amount"),
+        "authorization": {
+            "voucher_status": voucher_status,
+            "manual_console_steps_completed": list(completed),
+        },
+    }
+    return (len(errors) == 0, errors, normalized)