shopping-cli 3.0.0__py3-none-any.whl

shopping_cli/api/auth.py

@@ -0,0 +1,125 @@
+"""API authentication and bearer-token payload helpers."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from shopping_cli.core.channels import normalize_channel
+from shopping_cli.core.errors import AuthError
+from shopping_cli.core.tokens import token_matches
+from shopping_cli.config import secret_is_usable
+from shopping_cli.api.limits import validate_payload
+
+
+def payload_token(payload: dict[str, Any]) -> str:
+    return str(
+        payload.get("merchant_token")
+        or payload.get("agent_token")
+        or payload.get("buyer_token")
+        or payload.get("_auth_token")
+        or ""
+    )
+
+
+def payload_admin_token(payload: dict[str, Any]) -> str:
+    return str(payload.get("admin_token") or payload.get("_auth_token") or "")
+
+
+def payload_channel_token(payload: dict[str, Any]) -> str:
+    return str(payload.get("channel_token") or payload.get("_auth_token") or "")
+
+
+def payload_buyer_bootstrap_token(payload: dict[str, Any]) -> str:
+    return str(payload.get("buyer_bootstrap_token") or payload.get("_auth_token") or "")
+
+
+def payload_with_auth(
+    payload: dict[str, Any],
+    authorization: Any = "",
+    idempotency_key: Any = "",
+) -> dict[str, Any]:
+    validate_payload(payload)
+    merged = dict(payload or {})
+    if isinstance(authorization, str) and authorization.lower().startswith("bearer "):
+        merged["_auth_token"] = authorization.split(" ", 1)[1].strip()
+    if isinstance(idempotency_key, str) and idempotency_key.strip():
+        merged["_idempotency_key"] = idempotency_key.strip()
+    return merged
+
+
+def configured_admin_token() -> str:
+    return str(os.environ.get("SHOPPING_ADMIN_TOKEN") or "").strip()
+
+
+def configured_buyer_bootstrap_token() -> str:
+    return str(os.environ.get("SHOPPING_BUYER_BOOTSTRAP_TOKEN") or "").strip()
+
+
+def require_admin_token(payload: dict[str, Any]) -> None:
+    expected = configured_admin_token()
+    if not secret_is_usable(expected):
+        raise AuthError("admin bootstrap token is not configured")
+    token = payload_admin_token(payload)
+    if not token:
+        raise AuthError("admin bootstrap token required")
+    if not token_matches(token, expected):
+        raise AuthError("invalid admin bootstrap token")
+
+
+def require_buyer_bootstrap_token(payload: dict[str, Any], digest_fn: Any) -> str:
+    expected = configured_buyer_bootstrap_token()
+    if not secret_is_usable(expected):
+        raise AuthError("buyer bootstrap token is not configured")
+    token = payload_buyer_bootstrap_token(payload)
+    if not token:
+        raise AuthError("buyer bootstrap token required")
+    if not token_matches(token, expected):
+        raise AuthError("invalid buyer bootstrap token")
+    return digest_fn(token)
+
+
+def channel_token_map() -> dict[str, str]:
+    tokens: dict[str, str] = {}
+    global_token = str(os.environ.get("SHOPPING_CHANNEL_TOKEN") or "").strip()
+    if secret_is_usable(global_token):
+        tokens["*"] = global_token
+    raw = str(os.environ.get("SHOPPING_CHANNEL_TOKENS") or "").strip()
+    if not raw:
+        return tokens
+    try:
+        decoded = json.loads(raw)
+    except json.JSONDecodeError:
+        decoded = None
+    if isinstance(decoded, dict):
+        for channel, token in decoded.items():
+            normalized = normalize_channel(str(channel))
+            if normalized and secret_is_usable(str(token or "")):
+                tokens[normalized] = str(token).strip()
+        return tokens
+    for part in raw.replace("\n", ",").split(","):
+        text = part.strip()
+        if not text:
+            continue
+        separator = ":" if ":" in text else "=" if "=" in text else ""
+        if not separator:
+            continue
+        channel, token = text.split(separator, 1)
+        normalized = normalize_channel(channel)
+        if normalized and secret_is_usable(token):
+            tokens[normalized] = token.strip()
+    return tokens
+
+
+def require_channel_token(channel: str, payload: dict[str, Any]) -> None:
+    normalized = normalize_channel(channel)
+    tokens = channel_token_map()
+    expected = tokens.get(normalized) or tokens.get("*") or ""
+    if not expected:
+        raise AuthError(f"channel token is not configured for {normalized or '-'}")
+    token = payload_channel_token(payload)
+    if not token:
+        raise AuthError("channel token required")
+    if not token_matches(token, expected):
+        raise AuthError("invalid channel token")

shopping_cli/api/fallback_asgi.py

@@ -0,0 +1,219 @@
+"""Lightweight ASGI fallback used when FastAPI is unavailable."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, Callable
+from urllib.parse import parse_qs
+
+from shopping_cli.api import auth as api_auth
+from shopping_cli.api.limits import max_request_body_bytes
+
+
+def compute_etag(content: str | bytes) -> str:
+    """Compute a strong ETag (quoted content hash) for an HTTP response body.
+
+    Same semantics as the discovery cache module used before v3.0 (the Agent
+    Catalog subsystem moved to the standalone kiwi-catalog service): the same
+    content always yields the same ETag, and the value is opaque to clients.
+    """
+    if isinstance(content, str):
+        content = content.encode("utf-8")
+    return f'"{hashlib.sha256(content).hexdigest()}"'
+
+
+def etag_matches(if_none_match: str, etag: str) -> bool:
+    """True when an ``If-None-Match`` header value matches *etag*.
+
+    Handles strong and weak ETags and the ``*`` wildcard.  The header is
+    untrusted request data; every comparison is against the server's own
+    computed *etag*, so a malformed header simply never matches.
+    """
+    expected = etag.strip('"')
+    for raw in if_none_match.split(","):
+        token = raw.strip()
+        if token == "*":
+            return True
+        if token.startswith("W/"):
+            token = token[2:].strip()
+        token = token.strip('"')
+        if token and token == expected:
+            return True
+    return False
+
+
+HandleRequest = Callable[[str | Path, str, str, dict[str, Any] | None, dict[str, Any] | None], tuple[int, dict[str, Any]]]
+RouteProvider = Callable[[], list[Any]]
+RouteResolver = Callable[[str, str], tuple[bool, bool]]
+
+
+class MarketplaceASGIApp:
+    title = "shopping-cli Marketplace API"
+
+    def __init__(
+        self,
+        db_path: str | Path,
+        handle_request_fn: HandleRequest | None = None,
+        route_provider: RouteProvider | None = None,
+        route_resolver: RouteResolver | None = None,
+    ):
+        self.state = SimpleNamespace(db_path=str(db_path), fastapi_available=False)
+        self._handle_request = handle_request_fn
+        self._route_provider = route_provider
+        self._route_resolver = route_resolver
+        self.routes = self._routes()
+
+    def _routes(self) -> list[Any]:
+        provider = self._route_provider
+        if provider is None:
+            from shopping_cli.api.route_registry import route_info
+
+            provider = route_info
+        return provider()
+
+    def _handler(self) -> HandleRequest:
+        if self._handle_request is None:
+            from shopping_cli.api.app import handle_request
+
+            self._handle_request = handle_request
+        return self._handle_request
+
+    def _resolver(self) -> RouteResolver:
+        if self._route_resolver is None:
+            if self._handle_request is not None:
+                # Custom handlers own their routing; stay permissive for them.
+                return lambda _method, _path: (True, True)
+            from shopping_cli.api.app import resolve_route
+
+            self._route_resolver = resolve_route
+        return self._route_resolver
+
+    async def __call__(self, scope: dict[str, Any], receive: Any, send: Any) -> None:
+        if scope.get("type") != "http":
+            await send({"type": "http.response.start", "status": 404, "headers": [(b"content-type", b"application/json")]})
+            await send({"type": "http.response.body", "body": b'{"ok":false,"error":"unsupported scope"}'})
+            return
+        headers = {
+            key.decode("latin1").lower(): value.decode("latin1")
+            for key, value in scope.get("headers", [])
+        }
+        maximum = max_request_body_bytes()
+        try:
+            content_length = int(headers.get("content-length", "0") or 0)
+        except ValueError:
+            content_length = 0
+        if content_length > maximum:
+            await self._send_json(send, 413, {"ok": False, "error": "request body is too large"})
+            return
+        method = str(scope.get("method") or "GET").upper()
+        path = str(scope.get("path") or "/")
+        path_known, method_allowed = self._resolver()(method, path)
+        if not path_known:
+            await self._send_json(send, 404, {"ok": False, "error": f"No route for {method} {path}"})
+            return
+        if not method_allowed:
+            await self._send_json(send, 405, {"ok": False, "error": f"Method not allowed for {method} {path}"})
+            return
+        chunks: list[bytes] = []
+        body_size = 0
+        while True:
+            message = await receive()
+            chunk = message.get("body", b"")
+            body_size += len(chunk)
+            if body_size > maximum:
+                await self._send_json(send, 413, {"ok": False, "error": "request body is too large"})
+                return
+            chunks.append(chunk)
+            if not message.get("more_body", False):
+                break
+        try:
+            decoded_payload = json.loads(b"".join(chunks).decode("utf-8") or "{}")
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            body = json.dumps(
+                {"ok": False, "error": "invalid JSON request body"},
+                ensure_ascii=False,
+                sort_keys=True,
+            ).encode("utf-8")
+            await send({"type": "http.response.start", "status": 400, "headers": [(b"content-type", b"application/json")]})
+            await send({"type": "http.response.body", "body": body})
+            return
+        if not isinstance(decoded_payload, dict):
+            body = json.dumps(
+                {"ok": False, "error": "JSON request body must be an object"},
+                ensure_ascii=False,
+                sort_keys=True,
+            ).encode("utf-8")
+            await send({"type": "http.response.start", "status": 400, "headers": [(b"content-type", b"application/json")]})
+            await send({"type": "http.response.body", "body": body})
+            return
+        payload = decoded_payload
+        payload = api_auth.payload_with_auth(
+            payload,
+            authorization=headers.get("authorization", ""),
+            idempotency_key=headers.get("idempotency-key", ""),
+        )
+        try:
+            raw_query = scope.get("query_string", b"").decode("utf-8")
+        except UnicodeDecodeError:
+            raw_query = ""
+        query = parse_qs(raw_query, keep_blank_values=True)
+        status, response = await asyncio.to_thread(
+            self._handler(),
+            self.state.db_path,
+            method,
+            path,
+            payload,
+            {key: values[-1] if values else "" for key, values in query.items()},
+        )
+        await self._send_json(
+            send,
+            status,
+            response,
+            if_none_match=headers.get("if-none-match", ""),
+            allow_304=method == "GET",
+        )
+
+    @staticmethod
+    async def _send_json(
+        send: Any,
+        status: int,
+        response: dict[str, Any],
+        *,
+        if_none_match: str = "",
+        allow_304: bool = False,
+    ) -> None:
+        """Serialize *response* with a §18 server-side ETag.
+
+        When the caller allows conditional GET and the client's
+        ``If-None-Match`` matches the computed ETag, a body-less 304 is sent.
+        """
+        body = json.dumps(response, ensure_ascii=False, sort_keys=True).encode("utf-8")
+        etag = compute_etag(body)
+        # A conditional GET only revalidates a *successful* representation:
+        # never 304 an error body (e.g. a 404 for If-None-Match: *).
+        if allow_304 and status == 200 and if_none_match and etag_matches(if_none_match, etag):
+            await send(
+                {
+                    "type": "http.response.start",
+                    "status": 304,
+                    "headers": [(b"etag", etag.encode("ascii"))],
+                }
+            )
+            await send({"type": "http.response.body", "body": b""})
+            return
+        await send(
+            {
+                "type": "http.response.start",
+                "status": status,
+                "headers": [
+                    (b"content-type", b"application/json"),
+                    (b"etag", etag.encode("ascii")),
+                    (b"content-length", str(len(body)).encode("ascii")),
+                ],
+            }
+        )
+        await send({"type": "http.response.body", "body": body})

shopping_cli/api/handlers/__init__.py

@@ -0,0 +1 @@
+"""HTTP handler modules for marketplace API domains."""

shopping_cli/api/handlers/agents.py

@@ -0,0 +1,277 @@
+"""Agent API handlers."""
+
+from __future__ import annotations
+
+import math
+from pathlib import Path
+from typing import Any
+
+from shopping_cli.agents import merchant_agent
+from shopping_cli.api import auth as api_auth
+from shopping_cli.api.handlers.common import (
+    DEFAULT_RESULT_LIMIT,
+    non_negative_whole_int,
+    positive_whole_int,
+    require_field,
+    result_limit,
+    result_offset,
+)
+from shopping_cli.config import agent_stale_ttl_seconds_from
+from shopping_cli.core.conversations import conversation_summary
+from shopping_cli.core.errors import AuthError, ValidationError
+from shopping_cli.core.harness import (
+    abandon_agent_message,
+    abandon_stale_agent_messages,
+    agent_message_process_summary,
+    claim_agent_message,
+    complete_agent_message,
+    fail_agent_message,
+)
+from shopping_cli.db.session import db_session
+from shopping_cli.services import agents as agent_service
+from shopping_cli.services import tokens as token_service
+
+
+def _payload_token(payload: dict[str, Any]) -> str:
+    return api_auth.payload_token(payload)
+
+
+def _positive_whole_seconds(value: Any, field_name: str) -> int | None:
+    if value in (None, ""):
+        return None
+    if isinstance(value, bool):
+        raise ValidationError(f"{field_name} must be a whole number")
+    if isinstance(value, int):
+        seconds = value
+    elif isinstance(value, float):
+        if not math.isfinite(value) or not value.is_integer():
+            raise ValidationError(f"{field_name} must be a whole number")
+        seconds = int(value)
+    else:
+        try:
+            seconds = int(str(value).strip())
+        except ValueError as exc:
+            raise ValidationError(f"{field_name} must be a whole number") from exc
+    if seconds <= 0:
+        raise ValidationError(f"{field_name} must be greater than 0")
+    return seconds
+
+
+def default_merchant_agent_id(merchant_id: str) -> str:
+    return token_service.default_merchant_agent_id(merchant_id)
+
+
+def agent_heartbeat(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        merchant_id = str(require_field(payload, "merchant_id"))
+        agent_id = default_merchant_agent_id(merchant_id)
+        token_service.require_agent_or_merchant_token(conn, merchant_id, agent_id, _payload_token(payload))
+        agent = merchant_agent.heartbeat(
+            conn,
+            merchant_id=merchant_id,
+            status=str(payload.get("status") or "online"),
+            capabilities=payload.get("capabilities"),
+            pid=non_negative_whole_int(payload.get("pid"), "pid"),
+            version=str(payload.get("version") or ""),
+            last_error=str(payload.get("last_error") or ""),
+            checked_count=non_negative_whole_int(payload.get("checked_count"), "checked_count"),
+            replied_count=non_negative_whole_int(payload.get("replied_count"), "replied_count"),
+        )
+        return {"ok": True, "agent": agent}
+
+
+def create_agent_token(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        merchant_id = str(require_field(payload, "merchant_id"))
+        token_service.require_merchant_token(conn, merchant_id, _payload_token(payload))
+        return agent_service.issue_agent_token_for_merchant(
+            conn,
+            merchant_id,
+            agent_id=str(payload.get("agent_id") or ""),
+            ttl_seconds=payload.get("ttl_seconds"),
+            positive_whole_seconds=_positive_whole_seconds,
+        )
+
+
+def list_agent_tokens(
+    db_path: str | Path,
+    payload: dict[str, Any],
+    merchant_id: str = "",
+    limit: Any = DEFAULT_RESULT_LIMIT,
+    offset: Any = 0,
+) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        resolved_merchant_id = str(merchant_id or payload.get("merchant_id") or "")
+        if not resolved_merchant_id:
+            raise ValidationError("merchant_id is required")
+        token_service.require_merchant_token(conn, resolved_merchant_id, _payload_token(payload))
+        return agent_service.list_agent_tokens(
+            conn,
+            resolved_merchant_id,
+            limit=result_limit(limit),
+            offset=result_offset(offset),
+        )
+
+
+def revoke_agent_token(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        merchant_id = str(require_field(payload, "merchant_id"))
+        token_service.require_merchant_token(conn, merchant_id, _payload_token(payload))
+        return agent_service.revoke_agent_token(
+            conn,
+            merchant_id,
+            token=payload.get("token"),
+            token_prefix=payload.get("token_prefix"),
+        )
+
+
+def rotate_agent_token(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        merchant_id = str(require_field(payload, "merchant_id"))
+        token_service.require_merchant_token(conn, merchant_id, _payload_token(payload))
+        return agent_service.rotate_agent_token(
+            conn,
+            merchant_id,
+            token=payload.get("token"),
+            token_prefix=payload.get("token_prefix"),
+            ttl_seconds=payload.get("ttl_seconds"),
+            positive_whole_seconds=_positive_whole_seconds,
+        )
+
+
+def require_agent_payload(conn: Any, payload: dict[str, Any]) -> tuple[str, str]:
+    merchant_id = str(require_field(payload, "merchant_id"))
+    agent_id = str(payload.get("agent_id") or default_merchant_agent_id(merchant_id))
+    token_service.require_agent_or_merchant_token(conn, merchant_id, agent_id, _payload_token(payload))
+    return merchant_id, agent_id
+
+
+def require_agent_conversation(conn: Any, merchant_id: str, conversation_id: str) -> dict[str, Any]:
+    conversation = conversation_summary(conn, conversation_id)
+    if conversation["merchant_id"] != merchant_id:
+        raise AuthError(f"Merchant {merchant_id} cannot access conversation {conversation_id}")
+    return conversation
+
+
+def require_message_in_conversation(conn: Any, conversation_id: str, message_id: int) -> None:
+    agent_service.validate_buyer_message_for_claim(conn, conversation_id, message_id)
+
+
+def require_agent_process_scope(conn: Any, merchant_id: str, agent_id: str, message_id: int) -> dict[str, Any]:
+    process = agent_message_process_summary(conn, agent_id, message_id)
+    require_agent_conversation(conn, merchant_id, process["conversation_id"])
+    return process
+
+
+def claim_message(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        merchant_id, agent_id = require_agent_payload(conn, payload)
+        conversation_id = str(require_field(payload, "conversation_id"))
+        require_agent_conversation(conn, merchant_id, conversation_id)
+        message_id = positive_whole_int(require_field(payload, "message_id"), "message_id")
+        require_message_in_conversation(conn, conversation_id, message_id)
+        # 回合/乱序防护（与 negotiation claim 一致）：只能 claim 处于
+        # waiting_merchant 且是**最新**买家消息——否则回答会落在旧问题上，
+        # 更新的买家消息还会被再次派发（跨消息跳答）。
+        conversation = conversation_summary(conn, conversation_id)
+        if str(conversation["status"] or "") != "waiting_merchant":
+            raise ConflictError(
+                f"Conversation {conversation_id} is not waiting for the merchant agent "
+                f"(status={conversation['status']!r})"
+            )
+        latest_row = conn.execute(
+            "select id from messages where conversation_id = ? and sender = 'buyer' "
+            "order by id desc limit 1",
+            (conversation_id,),
+        ).fetchone()
+        if latest_row is None or int(latest_row["id"]) != message_id:
+            raise ConflictError(f"Message {message_id} is not the latest buyer message")
+        claim = claim_agent_message(
+            conn,
+            agent_id,
+            conversation_id,
+            message_id,
+            str(require_field(payload, "idempotency_key")),
+        )
+        return {"ok": True, "claim": claim}
+
+
+def complete_message(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        merchant_id, agent_id = require_agent_payload(conn, payload)
+        message_id = positive_whole_int(require_field(payload, "message_id"), "message_id")
+        require_agent_process_scope(conn, merchant_id, agent_id, message_id)
+        process = complete_agent_message(conn, agent_id, message_id)
+        return {"ok": True, "process": process}
+
+
+def fail_message(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        merchant_id, agent_id = require_agent_payload(conn, payload)
+        message_id = positive_whole_int(require_field(payload, "message_id"), "message_id")
+        require_agent_process_scope(conn, merchant_id, agent_id, message_id)
+        process = fail_agent_message(conn, agent_id, message_id, str(payload.get("error") or "agent failure"))
+        return {"ok": True, "process": process}
+
+
+def abandon_message(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        merchant_id, agent_id = require_agent_payload(conn, payload)
+        message_id = positive_whole_int(require_field(payload, "message_id"), "message_id")
+        require_agent_process_scope(conn, merchant_id, agent_id, message_id)
+        process = abandon_agent_message(conn, agent_id, message_id, str(payload.get("error") or "agent abandoned claim"))
+        return {"ok": True, "process": process}
+
+
+def abandon_stale_messages(db_path: str | Path, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        _merchant_id, agent_id = require_agent_payload(conn, payload)
+        abandoned = abandon_stale_agent_messages(
+            conn,
+            agent_id,
+            stale_after_seconds=(
+                _positive_whole_seconds(payload.get("stale_after_seconds", 300), "stale_after_seconds") or 300
+            ),
+        )
+        return {"ok": True, "abandoned": abandoned}
+
+
+def list_agents(
+    db_path: str | Path,
+    payload: dict[str, Any],
+    owner_id: str = "",
+    limit: Any = DEFAULT_RESULT_LIMIT,
+    offset: Any = 0,
+) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        scoped_owner_id = str(owner_id or "")
+        if scoped_owner_id:
+            token_service.require_merchant_read_token(conn, scoped_owner_id, _payload_token(payload))
+        else:
+            token_row = token_service.require_api_token(conn, _payload_token(payload), "agent read token required")
+            if token_row["role"] not in {"merchant", "agent"} or not token_row["merchant_id"]:
+                raise AuthError("invalid agent read token")
+            scoped_owner_id = str(token_row["merchant_id"])
+        return {
+            "ok": True,
+            "agents": agent_service.list_agent_summaries(
+                conn,
+                owner_id=scoped_owner_id,
+                limit=result_limit(limit),
+                offset=result_offset(offset),
+                include_stale=True,
+                stale_ttl_seconds=agent_stale_ttl_seconds_from(),
+            ),
+        }
+
+
+def get_agent(db_path: str | Path, agent_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+    with db_session(db_path) as conn:
+        summary = agent_service.get_agent_summary(
+            conn,
+            agent_id,
+            include_stale=True,
+            stale_ttl_seconds=agent_stale_ttl_seconds_from(),
+        )
+        token_service.require_merchant_read_token(conn, summary["owner_id"], _payload_token(payload))
+        return {"ok": True, "agent": summary}