"""Client-side value rules of the config plane wire contract. - :func:`to_wire` — YAML-derived Python values → JSON values (contract.md §4.1, §4.2). Runs on the whole new user-layer document BEFORE the diff, so a conversion never shows up as a change (§4.3). - :func:`secret_literal_path` — the secret-shaped-key rule (§14, D17), driven by the vendored ``config-secret-keys.json`` fixture so the agent and the plane use one list. The plane re-checks every write; this check exists so a literal is never sent. """ from __future__ import annotations import datetime import json import logging import math import re from functools import lru_cache from pathlib import Path as _FsPath from typing import Any, Dict, Iterator, Optional, Sequence, Tuple from hermes_cli.config_backend import ConfigValueError from .paths import Path, encode logger = logging.getLogger(__name__) MAX_SAFE_INTEGER = 2**53 - 1 VENDOR_DIR = _FsPath(__file__).resolve().parent / "vendor" SECRET_KEYS_FIXTURE = VENDOR_DIR / "conformance" / "config-secret-keys.json" def to_wire(value: Any, path: Path = ()) -> Any: """``value`` converted per §4.1/§4.2; raises :class:`ConfigValueError` naming the path.""" if value is None or isinstance(value, (str, bool)): return value if isinstance(value, int): if -MAX_SAFE_INTEGER <= value <= MAX_SAFE_INTEGER: return value logger.warning("config path %s: integer %d is outside ±(2^53-1); sent as a decimal string", encode(path) or "", value) return str(value) if isinstance(value, float): if math.isnan(value) or math.isinf(value): raise ConfigValueError(f"{encode(path) or ''}: NaN/Infinity cannot be stored in Remote Config") return value if isinstance(value, datetime.datetime | datetime.date): return value.isoformat() if isinstance(value, list | tuple): return [to_wire(v, path) for v in value] if isinstance(value, dict): out: dict[str, Any] = {} for k, v in value.items(): key = _wire_key(k, path) if key in out: raise ConfigValueError( f"{encode(path + (key,))}: two keys become the same string key {key!r}") out[key] = to_wire(v, path + (key,)) return out raise ConfigValueError( f"{encode(path) or ''}: a {type(value).__name__} value cannot be stored in Remote Config") def _wire_key(key: Any, path: Path) -> str: if isinstance(key, str): return key if isinstance(key, int) and not isinstance(key, bool): return str(key) raise ConfigValueError( f"{encode(path) or ''}: a {type(key).__name__} mapping key ({key!r}) cannot be stored " "in Remote Config; quote it in YAML") # --- secret-shaped keys (§14) ----------------------------------------------------------------- @lru_cache(maxsize=1) def _secret_rules() -> dict[str, Any]: data = json.loads(SECRET_KEYS_FIXTURE.read_text(encoding="utf-8-sig")) return { "secret_keys": frozenset(data["secretKeys"]), "secret_suffixes": tuple(data["secretKeySuffixes"]), "non_secret_suffixes": tuple(data["nonSecretKeySuffixes"]), "env_keys": frozenset(data["envConfigKeys"]), "env_suffixes": tuple(data["envConfigKeySuffixes"]), "env_prefixes": tuple(data["envConfigKeyPrefixes"]), # fullmatch: Python's ``$`` also matches before a trailing newline, so ``re.match`` with the # fixture pattern would accept ``"${X}\n"`` (a fixture vector the plane rejects). "placeholder": re.compile(data["placeholderPattern"]), "non_secret_paths": frozenset(tuple(p) for p in data["nonSecretPaths"]), } def _is_env_config_key(key: str, rules: dict[str, Any]) -> bool: if "." in key: return False up = key.upper() return up in rules["env_keys"] or up.endswith(rules["env_suffixes"]) or up.startswith(rules["env_prefixes"]) def is_secret_path(segments: Sequence[str]) -> bool: """§14.2 on decoded segments (list indices already dropped).""" rules = _secret_rules() if tuple(segments) in rules["non_secret_paths"]: return False last = segments[-1] leaf = last.lower().replace("-", "_") if len(segments) == 1 and _is_env_config_key(last, rules): return not leaf.endswith(rules["non_secret_suffixes"]) return leaf in rules["secret_keys"] or leaf.endswith(rules["secret_suffixes"]) def _walk(value: Any, path: Path) -> Iterator[tuple[Path, Any]]: yield path, value if isinstance(value, dict): for k, v in value.items(): yield from _walk(v, path + (str(k),)) elif isinstance(value, list): for v in value: # list elements inherit the list's path (§14.3) yield from _walk(v, path) def secret_literal_path(path: Path, value: Any) -> Optional[Path]: """The first path under ``set path = value`` that holds a secret literal (§14.3), or None.""" placeholder = _secret_rules()["placeholder"] for node_path, node in _walk(value, path): if not node_path or not is_secret_path(node_path): continue if isinstance(node, bool) or node is None: continue if isinstance(node, str) and (node == "" or placeholder.fullmatch(node)): continue if isinstance(node, str | int | float): return node_path return None