chp-server 0.60.2__py3-none-any.whl

chp_server/__init__.py

@@ -0,0 +1,53 @@
+"""chp-server — independently installable reference CHP server.
+
+Assembly only: protocol semantics live in chp-core; domain behavior attaches
+through the `chp_server.ports` entry-point group. The only mandatory CHP
+dependency is chp-core (DEC-SRV-001) — importing this package must never pull
+an optional CHP package (PKG-009; enforced by tests/test_import_purity.py).
+"""
+
+from .config import ServerConfig
+from .features import FEATURES, FeatureDescriptor, FeatureRegistry
+from .introduction import (
+    EntryPointIntroductionPort,
+    IntroductionCoordinator,
+    RemoteChpIntroductionSource,
+    SourceTrustPolicy,
+)
+from .local import ExistingHostPort, LocalArtifactPort, LocalStandalonePorts
+from .resolver import DirectoryResolutionPort, advertisement_batch
+from .ports import ENTRY_POINT_GROUP, PORT_ROLES, Attachment, AttachmentRegistry
+from .profiles import CONFORMANCE_MANIFEST, PROFILES, validate_profile
+from .server import Server, ServerInstanceIdentity, ServerStatus
+from .app import CapabilityServer
+
+# Replay / ReplayEvent (the typed /replay view) live in chp_server.replay, not the
+# top-level namespace — API-008 keeps the public surface small and curated. Advanced
+# callers use `from chp_server.replay import Replay`; the CLI imports it directly.
+
+__all__ = [
+    "CapabilityServer",
+    "Attachment",
+    "AttachmentRegistry",
+    "CONFORMANCE_MANIFEST",
+    "ENTRY_POINT_GROUP",
+    "EntryPointIntroductionPort",
+    "ExistingHostPort",
+    "IntroductionCoordinator",
+    "SourceTrustPolicy",
+    "DirectoryResolutionPort",
+    "advertisement_batch",
+    "LocalArtifactPort",
+    "FEATURES",
+    "FeatureDescriptor",
+    "FeatureRegistry",
+    "LocalStandalonePorts",
+    "PORT_ROLES",
+    "PROFILES",
+    "RemoteChpIntroductionSource",
+    "Server",
+    "ServerConfig",
+    "ServerInstanceIdentity",
+    "ServerStatus",
+    "validate_profile",
+]

chp_server/_catalog.py

@@ -0,0 +1,60 @@
+"""Discover installed ``chp-adapter-*`` capability sets — the composable catalog.
+
+Enumerates adapters registered under the ``chp.adapters`` entry-point group and reads each
+one's ``@capability`` descriptors WITHOUT instantiating the adapter — so adapters that need
+configuration (API keys, backends) still list. A live catalog that can't rot: it reflects what
+is actually installed in this environment. Powers ``chp-server adapters``.
+"""
+
+from __future__ import annotations
+
+import inspect
+
+
+def _capabilities_of(cls: type) -> list[dict]:
+    """(id, description) for each capability an adapter class exposes.
+
+    First reads ``@capability`` method descriptors statically — config-free, no
+    instantiation (so adapters that need API keys/backends still list). If none are found,
+    the adapter likely builds its capabilities dynamically in ``capabilities()`` (e.g.
+    chp-core's GitAdapter via git_capabilities()); a static scan can't see those, so it
+    showed "0 caps". Try a SAFE no-arg instantiation to read them — an adapter that needs
+    configuration raises on ``__init__``/``capabilities()`` and is caught, staying capless
+    exactly as before (the config-free contract holds; only no-arg adapters gain coverage).
+    """
+    caps: list[dict] = []
+    seen: set[str] = set()
+    for _name, member in inspect.getmembers(cls):
+        descriptor = getattr(member, "__chp_descriptor__", None)
+        cid = getattr(descriptor, "id", None)
+        if cid and cid not in seen:
+            seen.add(cid)
+            caps.append({"id": cid, "description": (descriptor.description or "").strip()})
+    if not caps:
+        try:
+            for hosted in cls().capabilities():          # dynamic-capabilities() adapters
+                descriptor = getattr(hosted, "descriptor", None)
+                cid = getattr(descriptor, "id", None)
+                if cid and cid not in seen:
+                    seen.add(cid)
+                    caps.append({"id": cid,
+                                 "description": (getattr(descriptor, "description", "") or "").strip()})
+        except Exception:
+            pass  # needs config (or any error) -> report capless, config-free, unchanged
+    return sorted(caps, key=lambda c: c["id"])
+
+
+def adapter_catalog() -> list[dict]:
+    """Installed adapters as ``[{name, module, capabilities: [{id, description}]}]``, sorted by
+    name. Empty when no adapter packages are installed (a bare chp-server + chp-core env)."""
+    from chp_core.adapters import discover_adapters
+
+    catalog: list[dict] = []
+    for name, cls in sorted(discover_adapters().items()):
+        try:
+            caps = _capabilities_of(cls)
+        except Exception:
+            caps = []  # a broken adapter never sinks the catalog
+        catalog.append({"name": name, "module": getattr(cls, "__module__", "?"),
+                        "capabilities": caps})
+    return catalog

chp_server/_example.py

@@ -0,0 +1,45 @@
+"""Sample capabilities for ``chp-server serve --example``.
+
+A fresh ``chp serve`` starts a truthful ``protocol-only`` server where every
+optional feature is ``unsupported`` — honest, but there is nothing to invoke
+yet. ``--example`` attaches a governed host carrying a few harmless capabilities
+so the very first run is *live* and curl-able, and so the quickstart in the
+README works verbatim. It is a teaching aid, not a product surface.
+
+chp-core only — no other CHP package is imported.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from chp_core import CapabilityDescriptor, LocalCapabilityHost, SQLiteEvidenceStore
+
+
+def build_example_host(store_path: str, host_id: str = "chp-example") -> LocalCapabilityHost:
+    """A governed host with three sample capabilities: ``greet.hello``,
+    ``math.add`` and ``time.now``. Attach it with ``ExistingHostPort``."""
+    host = LocalCapabilityHost(host_id, store=SQLiteEvidenceStore(store_path))
+
+    host.register(
+        CapabilityDescriptor(
+            id="greet.hello", version="1.0.0", description="Greet a name.",
+            input_schema={"type": "object",
+                          "properties": {"name": {"type": "string"}}}),
+        lambda ctx, payload: {"greeting": f"hello, {payload.get('name', 'world')}"},
+    )
+    host.register(
+        CapabilityDescriptor(
+            id="math.add", version="1.0.0", description="Add two numbers.",
+            input_schema={"type": "object",
+                          "properties": {"a": {"type": "number"}, "b": {"type": "number"}}}),
+        lambda ctx, payload: {"sum": payload.get("a", 0) + payload.get("b", 0)},
+    )
+    host.register(
+        CapabilityDescriptor(
+            id="time.now", version="1.0.0",
+            description="Current UTC time as an ISO-8601 string."),
+        lambda ctx, payload: {
+            "now": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")},
+    )
+    return host

chp_server/_scaffold.py

@@ -0,0 +1,69 @@
+"""Scaffold a starter CHP capability server — the ``chp-server new`` command.
+
+Writes a single runnable Python file that serves one sample capability through the
+full CHP pipeline, so a newcomer goes from install to *their own* governed server in
+one command. The generated file needs only chp-core + chp-server.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+# Placeholders are substituted by str.replace (not str.format) so the template can
+# contain literal f-strings and dict/JSON braces without escaping every one.
+_TEMPLATE = '''#!/usr/bin/env python3
+"""A starter CHP capability server. Run it:  python __FILENAME__
+
+Serves your capabilities over HTTP with governed invocation and a signed, replayable
+evidence chain. Needs only chp-core + chp-server. See the serving guide:
+https://github.com/capabilityhostprotocol/chp-core
+"""
+from __future__ import annotations
+
+from chp_server import CapabilityServer
+
+app = CapabilityServer("__HOST_ID__")
+
+
+@app.capability("greet.hello")
+def hello(name: str = "world") -> dict:
+    """Greet a name."""
+    # The docstring becomes the description; the type hints become the input
+    # schema, which the pipeline enforces before this function runs.
+    return {"greeting": f"hello, {name}"}
+
+
+# TODO: add your own capabilities — one decorated function each.
+
+
+if __name__ == "__main__":
+    # try:  curl localhost:8800/invoke -H 'Content-Type: application/json' \\
+    #            -d '{"capability_id": "greet.hello", "payload": {"name": "CHP"}}'
+    app.run(port=8800)
+'''
+
+
+def _host_id(name: str) -> str:
+    """A safe host_id/slug from the requested name (letters, digits, dashes)."""
+    slug = re.sub(r"[^a-z0-9-]+", "-", Path(name).stem.lower()).strip("-")
+    return slug or "my-host"
+
+
+def _target_path(name: str) -> Path:
+    return Path(name if name.endswith(".py") else f"{name}.py")
+
+
+def render_starter(name: str) -> str:
+    """The generated starter file's source (does not touch disk)."""
+    path = _target_path(name)
+    return _TEMPLATE.replace("__FILENAME__", path.name).replace("__HOST_ID__", _host_id(name))
+
+
+def write_starter(name: str, *, force: bool = False) -> Path:
+    """Write the starter file next to the caller; refuse to clobber unless *force*."""
+    path = _target_path(name)
+    if path.exists() and not force:
+        raise FileExistsError(f"{path} already exists (use --force to overwrite)")
+    path.write_text(render_starter(name))
+    return path

chp_server/app.py

@@ -0,0 +1,132 @@
+"""``CapabilityServer`` — the clean, decorator-first way to surface capabilities.
+
+    from chp_server import CapabilityServer
+
+    app = CapabilityServer("my-host")
+
+    @app.capability("math.add")
+    def add(a: int, b: int) -> dict:
+        "Add two numbers."
+        return {"sum": a + b}
+
+    app.run(port=8800)
+
+`app.capability(...)` registers a governed capability from a plain function:
+
+- the **docstring** becomes the description,
+- the **type hints** become the input schema — and the pipeline *enforces* it: a
+  malformed call is denied (`input_schema_validation_failed`) before your handler runs,
+- payload fields arrive as **keyword arguments** (write `def add(a, b)`, not `payload`).
+
+It is thin sugar over `LocalCapabilityHost` + `Server.serving`; reach for the explicit
+host/attachment API (`ExistingHostPort`, resolution, federation, the distribute path,
+custom evidence stores) when you outgrow it. chp-core only.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import TYPE_CHECKING, Any, Callable
+
+from chp_core import LocalCapabilityHost, SQLiteEvidenceStore
+from chp_core.decorators import capability as _capability
+
+from .server import Server
+
+if TYPE_CHECKING:
+    from chp_core import CapabilityDescriptor
+
+
+class CapabilityServer:
+    """A host you decorate capabilities onto, then serve."""
+
+    def __init__(self, host_id: str = "chp-server", *, store: str | None = None) -> None:
+        self.host = LocalCapabilityHost(
+            host_id, store=SQLiteEvidenceStore(store or f"{host_id}.sqlite"))
+
+    def capability(self, id: str, *, version: str = "1.0.0",
+                   description: str | None = None,
+                   input_schema: dict | bool | None = None,
+                   **descriptor_kwargs: Any) -> Callable[[Callable], Callable]:
+        """Register the decorated function as a governed capability.
+
+        ``description`` defaults to the function's docstring; ``input_schema`` defaults
+        to one inferred from its type hints (pass a dict to override, or ``False`` to
+        declare none). Any other ``CapabilityDescriptor`` field (``policy``, ``risk``,
+        ``tags``, ``timeout_s``, ...) may be passed through.
+        """
+        def decorate(fn: Callable[..., Any]) -> Callable[..., Any]:
+            desc = description or (inspect.getdoc(fn) or "").strip() or id
+            # input_schema None -> infer from type hints (chp-core does it);
+            # False -> declare none; a dict -> use it verbatim.
+            explicit = input_schema if isinstance(input_schema, dict) else None
+            decorated = _capability(
+                id=id, version=version, description=desc,
+                input_schema=explicit, infer_schema=(input_schema is None),
+                **descriptor_kwargs)(fn)
+            self.host.register(decorated)
+            return decorated
+        return decorate
+
+    def compose(self, adapter: Any, *, replace: bool = False) -> list[CapabilityDescriptor]:
+        """Compose an EXISTING adapter's capabilities onto this server — the adapter-first
+        way to add git / http / secrets / filesystem / … without reimplementing them. A
+        server serves whatever mix it needs: hand-written ``@capability`` functions *and*
+        any ``chp-adapter-*`` (a ``chp_core.adapters.BaseAdapter`` of ``@capability``
+        methods). One governed implementation, reused here — not a parallel copy. Returns
+        the registered capability descriptors; ``replace=True`` overwrites duplicates (e.g.
+        an adapter re-created with new config)."""
+        from chp_core import register_adapter
+        return register_adapter(self.host, adapter, replace=replace)
+
+    def serving(self, **serving_kwargs: Any) -> Server:
+        """Build (do not start) a Server projecting this host — for embedding/tests."""
+        return Server.serving(self.host, **serving_kwargs)
+
+    def _served_capability_ids(self) -> list[str]:
+        """Best-effort list of capability ids the host serves (for the run() banner).
+
+        host.discover() returns a HostDescriptor dict ({..., "capabilities": [{"id": ...}]});
+        tolerate an object shape too so this never breaks the banner.
+        """
+        try:
+            desc = self.host.discover()
+        except Exception:
+            return []
+        caps = (desc.get("capabilities") if isinstance(desc, dict)
+                else getattr(desc, "capabilities", None)) or []
+        ids = []
+        for c in caps:
+            cid = c.get("id") if isinstance(c, dict) else getattr(c, "id", None)
+            if cid:
+                ids.append(cid)
+        return sorted(ids)
+
+    def run(self, *, port: int = 8800, bind: str = "127.0.0.1",
+            **serving_kwargs: Any) -> None:
+        """Serve this host over HTTP (blocking)."""
+        server = self.serving(port=port, bind=bind, **serving_kwargs)
+        server.start()
+        base = f"http://{bind}:{server.port}"
+        caps = self._served_capability_ids()
+        # A first-run banner that SHOWS the payoff: the URL, what's served, a ready-to-paste
+        # invoke, and the replay hint (the evidence chain is the point). flush=True so it
+        # appears immediately even when stdout is piped/redirected, not just on a tty.
+        print(f"chp-server serving at {base}  (Ctrl-C to stop)", flush=True)
+        if caps:
+            shown = ", ".join(caps[:8]) + (f"  (+{len(caps) - 8} more)" if len(caps) > 8 else "")
+            print(f"  {len(caps)} capabilit{'y' if len(caps) == 1 else 'ies'}: {shown}", flush=True)
+            print("  try it:", flush=True)
+            print(f"    curl -s {base}/invoke -H 'Content-Type: application/json' \\", flush=True)
+            print(f"         -d '{{\"capability_id\": \"{caps[0]}\", \"payload\": {{}}}}'", flush=True)
+            print(f"    curl -s {base}/replay/<correlation_id>   # the signed evidence chain",
+                  flush=True)
+        else:
+            print(f"  no capabilities registered — GET {base}/server for honest feature truth",
+                  flush=True)
+        try:
+            server.serve_forever()
+        except KeyboardInterrupt:
+            pass
+        finally:
+            server.stop()

chp_server/cli.py

@@ -0,0 +1,163 @@
+"""chp-server CLI — `chp serve` (via the chp-core shim) lands here."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="chp-server",
+        description="Reference CHP server: chp-core protocol surface + optional attachments.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    serve = sub.add_parser("serve", help="Start the server (blocking).")
+    serve.add_argument("--bind", default=None)
+    serve.add_argument("--port", type=int, default=None)
+    serve.add_argument("--profile", default=None)
+    serve.add_argument("--config", default=None, metavar="FILE", help="JSON config file")
+    serve.add_argument("--store", default=None, metavar="PATH", help="Evidence store path")
+    serve.add_argument("--example", action="store_true",
+                       help="Attach a few sample capabilities (greet.hello, math.add, "
+                            "time.now) so the server is live and curl-able on first run.")
+
+    describe = sub.add_parser("describe", help="Print Server.Describe for a config without serving.")
+    describe.add_argument("--config", default=None, metavar="FILE")
+    describe.add_argument("--profile", default=None)
+
+    new = sub.add_parser("new", help="Scaffold a runnable starter capability server.")
+    new.add_argument("name", help="Starter file to create, e.g. 'mycaps' or 'mycaps.py'.")
+    new.add_argument("--force", action="store_true", help="Overwrite if the file exists.")
+
+    adapters = sub.add_parser(
+        "adapters", help="List installed chp-adapter-* capability sets you can compose().")
+    adapters.add_argument("--verbose", action="store_true",
+                          help="Show each capability id + description.")
+    adapters.add_argument("--json", action="store_true", help="Emit the catalog as JSON.")
+
+    replay = sub.add_parser(
+        "replay", help="Pretty-print a GET /replay evidence chain (JSON from stdin or --file).")
+    replay.add_argument("--file", default=None, metavar="PATH",
+                        help="Read the /replay JSON from a file instead of stdin.")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "replay":
+        from .replay import Replay
+        if args.file:
+            try:
+                raw = open(args.file).read()
+            except OSError as exc:
+                print(f"ERROR: {exc}", file=sys.stderr)
+                return 1
+        elif sys.stdin.isatty():
+            # No --file and an interactive stdin: NEVER block on stdin.read() (that hung a
+            # CLI invocation indefinitely). Show usage and exit instead.
+            print("chp-server replay: pipe a /replay response, or pass --file. e.g.\n"
+                  "  curl -s http://127.0.0.1:8800/replay/<correlation_id> | chp-server replay\n"
+                  "  chp-server replay --file replay.json", file=sys.stderr)
+            return 2
+        else:
+            raw = sys.stdin.read()
+        try:
+            doc = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            print(f"ERROR: input is not valid JSON ({exc}). Pipe a /replay response, e.g.:\n"
+                  "  curl -s http://127.0.0.1:8800/replay/<correlation_id> | chp-server replay",
+                  file=sys.stderr)
+            return 1
+        print(Replay.from_wire(doc).render())
+        return 0
+
+    if args.command == "adapters":
+        from ._catalog import adapter_catalog
+        catalog = adapter_catalog()
+        if getattr(args, "json", False):
+            print(json.dumps(catalog, indent=2))
+            return 0
+        if not catalog:
+            print("No chp-adapter-* packages installed in this environment.\n"
+                  "Install some (e.g. pip install chp-adapter-filesystem), then compose them:\n"
+                  "  app.compose(FilesystemAdapter(...))")
+            return 0
+        total = sum(len(a["capabilities"]) for a in catalog)
+        print(f"{len(catalog)} adapters installed ({total} capabilities) — "
+              "compose with app.compose(AdapterClass(...)):\n")
+        for a in catalog:
+            print(f"  {a['name']:24} {len(a['capabilities']):>3} caps")
+            if getattr(args, "verbose", False):
+                for c in a["capabilities"]:
+                    print(f"       {c['id']}  —  {c['description'][:68]}")
+        return 0
+
+    if args.command == "new":
+        from ._scaffold import write_starter
+        try:
+            path = write_starter(args.name, force=args.force)
+        except OSError as exc:
+            print(f"ERROR: {exc}", file=sys.stderr)
+            return 1
+        print(f"Created {path} — run it with:  python {path}")
+        return 0
+
+    from .config import ServerConfig
+    from .server import Server
+
+    # --example needs a host to attach to; default it into the `host` profile
+    # unless the caller chose one explicitly.
+    example = getattr(args, "example", False)
+    profile = args.profile or ("host" if example else None)
+
+    try:
+        config = ServerConfig.from_sources(
+            config_file=args.config, bind=getattr(args, "bind", None),
+            port=getattr(args, "port", None), profile=profile,
+            store=getattr(args, "store", None))
+    except (ValueError, OSError) as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+    server = Server(config)
+
+    example_dir = None
+    if example:
+        import os
+        import tempfile
+        from ._example import build_example_host
+        from .local import ExistingHostPort
+        example_dir = tempfile.mkdtemp(prefix="chp-example-")
+        server.attach(ExistingHostPort(
+            build_example_host(os.path.join(example_dir, "example.sqlite"))))
+
+    if args.command == "describe":
+        print(json.dumps(server.describe(), indent=2))
+        return 0
+
+    try:
+        server.start()
+    except RuntimeError as exc:  # fail-closed profile validation
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+    print(f"chp-server {server.identity.instance_id} serving profile "
+          f"{config.profile!r} at http://{config.bind}:{server.port}")
+    print("Routes: GET /health /ready /server /host /capabilities, POST /invoke")
+    if example:
+        base = f"http://{config.bind}:{server.port}"
+        print("\nSample capabilities attached — try:")
+        print(f"  curl {base}/capabilities.txt")
+        print(f"  curl {base}/invoke -H 'Content-Type: application/json' \\")
+        print("       -d '{\"capability_id\": \"greet.hello\", \"payload\": {\"name\": \"CHP\"}}'")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.stop()
+    print("\nStopped chp-server.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

chp_server/config.py

@@ -0,0 +1,77 @@
+"""ServerConfig — deterministic precedence + generations (doc 40).
+
+Precedence: built-in defaults -> config file (JSON) -> environment -> explicit
+programmatic overrides. Effective configuration is inspectable with secrets
+redacted; unknown fields fail validation.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+from typing import Any
+
+from chp_core.environment import current_environment, validate_environment
+
+_ENV_PREFIX = "CHP_SERVER_"
+_SECRET_FIELDS = ("tls_keyfile",)
+
+
+@dataclass
+class ServerConfig:
+    bind: str = "127.0.0.1"
+    port: int = 8770
+    profile: str = "protocol-only"
+    environment: str = field(default_factory=current_environment)
+    host_id: str = "chp-server"
+    store: str | None = None            # evidence store path; None = chp-core default
+    tls_certfile: str | None = None
+    tls_keyfile: str | None = None
+    tls_cafile: str | None = None
+    # attachments: {entry_point_name: {kwargs}} — Phase B config (doc 40 §3);
+    # only listed attachments are loaded even when more are installed.
+    attachments: dict[str, dict] = field(default_factory=dict)
+    # HA multi-instance (HA-003): when enabled, instances of one logical Host contend
+    # for a store-backed ownership lease; only the ACTIVE holder admits consequential
+    # work, standby refuses server_not_active. Requires a SHARED `store` all instances
+    # point at. Off = single-instance (always active). ttl = lease/heartbeat window.
+    ha_enabled: bool = False
+    ha_lease_ttl_s: float = 30.0
+
+    def __post_init__(self) -> None:
+        validate_environment(self.environment)
+        from .profiles import PROFILES
+        if self.profile not in PROFILES:
+            raise ValueError(f"unknown profile {self.profile!r}; valid: {sorted(PROFILES)}")
+
+    @classmethod
+    def from_sources(cls, config_file: str | Path | None = None,
+                     env: dict[str, str] | None = None, **overrides: Any) -> "ServerConfig":
+        env = os.environ if env is None else env
+        known = {f.name for f in fields(cls)}
+        merged: dict[str, Any] = {}
+        if config_file:
+            data = json.loads(Path(config_file).read_text())
+            unknown = set(data) - known
+            if unknown:  # unknown fields fail closed (doc 40 §7)
+                raise ValueError(f"unknown configuration fields: {sorted(unknown)}")
+            merged.update(data)
+        for f in fields(cls):
+            key = _ENV_PREFIX + f.name.upper()
+            if key in env:
+                raw = env[key]
+                merged[f.name] = int(raw) if f.type == "int" else raw
+        merged.update({k: v for k, v in overrides.items() if v is not None})
+        unknown = set(merged) - known
+        if unknown:
+            raise ValueError(f"unknown configuration fields: {sorted(unknown)}")
+        return cls(**merged)
+
+    def redacted(self) -> dict:
+        d = {f.name: getattr(self, f.name) for f in fields(self)}
+        for k in _SECRET_FIELDS:
+            if d.get(k):
+                d[k] = "<redacted>"
+        return d