flowstatemcp 2.5.0__py3-none-any.whl

flowstate/relay/cli.py

@@ -0,0 +1,344 @@
+"""`flowstate relay ...` commands. Plain-language output; never prints the device token or a key.
+
+    flowstate relay enroll --code CODE [--staging] [--skip-cert]
+    flowstate relay run    [--db FILE] [--port 8768]
+    flowstate relay status
+    flowstate relay renew  [--force] [--staging | --production]
+    flowstate relay enable | disable
+    flowstate relay forget [--yes]
+    flowstate relay ct-check
+    flowstate relay ct-ack --id CRTSH_ID
+    flowstate relay chat-approvals [on|off] [--db FILE]
+
+For relay developers only: FLOWSTATE_RELAY_DOMAIN (default fsmcp.com), FLOWSTATE_RELAY_API,
+FLOWSTATE_RELAY_TUNNEL (host:port), FLOWSTATE_RELAY_TUNNEL_SNI, FLOWSTATE_RELAY_CA_FILE,
+FLOWSTATE_RELAY_ACME_DIRECTORY and FLOWSTATE_RELAY_DIR point the agent somewhere else (https
+only, except loopback). Every relay command prints a warning first when FLOWSTATE_RELAY_DOMAIN
+is anything other than fsmcp.com.
+"""
+
+import os
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+from . import API_BASE, TUNNEL_HOST, TUNNEL_PORT, RelayError, RelayWaitlisted
+from .. import term
+
+
+def say(msg: str) -> None:
+    # text from apps and records is in many lines: no escape code reaches the terminal (NEW-7)
+    print(term.safe(msg, newlines=True), flush=True)
+
+
+def _store():
+    from .store import RelayStore
+    return RelayStore()
+
+
+def _when(ts) -> str:
+    return datetime.fromtimestamp(ts).strftime("%Y-%m-%d %H:%M") if ts else "never"
+
+
+def _tunnel_env():
+    raw = os.environ.get("FLOWSTATE_RELAY_TUNNEL") or f"{TUNNEL_HOST}:{TUNNEL_PORT}"
+    host, _, port = raw.rpartition(":")
+    if not host or not port.isdigit():
+        raise RelayError("FLOWSTATE_RELAY_TUNNEL must be host:port")
+    return host, int(port), os.environ.get("FLOWSTATE_RELAY_TUNNEL_SNI") or TUNNEL_HOST
+
+
+# ---------------------------------------------------------------- commands
+def cmd_enroll(a) -> int:
+    from . import acme, api
+    from . import crypto as C
+    store = _store()
+    if not C.available():
+        say("The relay needs the Python package 'cryptography', which is not installed here. "
+            "Nothing was changed.")
+        return 1
+    if store.enrolled():
+        cfg = store.config()
+        say(f"Already enrolled as {cfg.get('hostname')}. To start over: flowstate relay forget")
+        return 1
+    base = os.environ.get("FLOWSTATE_RELAY_API") or API_BASE
+    api.check_url(base)
+    host, port, sni = _tunnel_env()
+    ca = os.environ.get("FLOWSTATE_RELAY_CA_FILE")
+    store.ensure_dir()  # refuses a git folder before anything goes over the network
+    try:
+        got = api.enroll(base, a.code, api.client_context(ca))
+    except RelayWaitlisted as e:
+        say(str(e))
+        say("No token or key was saved on this computer. Local FlowState keeps working as before.")
+        return 1
+    store.save_enrollment(got["handle"], got["device_token"], api=base, tunnel_host=host,
+                          tunnel_port=port, tunnel_sni=sni, staging=a.staging, ca_file=ca)
+    acme.new_tls_key(store)
+    say(f"Enrolled. Your relay address: https://{got['hostname']}/mcp")
+    say(f"Device token and keys saved (owner-only) in {store.root}. The TLS key was made on "
+        f"this computer and never leaves it.")
+    if a.skip_cert:
+        say("Certificate: not requested yet (flowstate relay renew, or it happens on `relay run`).")
+    else:
+        rc = _renew(store, force=False)
+        if rc:
+            say("Enrollment is kept; `flowstate relay run` will try the certificate again.")
+    say("Next: set the owner passphrase if you haven't (flowstate remote passphrase), then "
+        "start it with: flowstate relay run")
+    return 0
+
+
+def _renew(store, force: bool) -> int:
+    from . import acme
+    try:
+        r = acme.ensure_cert(store, force=force)
+    except RelayError as e:
+        say(f"Certificate NOT obtained: {e}")
+        return 1
+    info = r["info"]
+    staging = " (Let's Encrypt STAGING: browsers and AI apps will not trust it)" \
+        if store.config().get("staging") else ""
+    if r["renewed"]:
+        say(f"Certificate obtained for {', '.join(info['names'])}, valid until "
+            f"{info['not_after']:%Y-%m-%d}{staging}.")
+    else:
+        say(f"Certificate is fine until {info['not_after']:%Y-%m-%d}{staging}; nothing to do.")
+    return 0
+
+
+def cmd_renew(a) -> int:
+    store = _store()
+    if not store.enrolled():
+        say("The relay is not set up (flowstate relay enroll --code <code>).")
+        return 1
+    force = a.force
+    if a.staging or a.production:
+        cfg = store.config()
+        want = bool(a.staging)
+        if bool(cfg.get("staging")) != want:
+            cfg["staging"] = want
+            store.save_config(cfg)
+            force = True
+    return _renew(store, force)
+
+
+def cmd_run(a) -> int:
+    import asyncio
+    import logging
+    from . import runner
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(levelname)s %(message)s")
+    db = Path(a.db).expanduser() if a.db else None
+    try:
+        asyncio.run(runner.run(db_path=db, port=a.port))
+    except KeyboardInterrupt:
+        say("Relay stopped.")
+    return 0
+
+
+def cmd_status(a) -> int:
+    from . import crypto as C
+    from .store import CERT, STATUS_FRESH_SECONDS, active_alerts
+    store = _store()
+    cfg = store.config()
+    if not cfg.get("handle"):
+        say("Relay: not set up (off). Local FlowState works without it.")
+        return 0
+    say(f"Relay: {'ON' if cfg.get('enabled') else 'OFF (flowstate relay enable)'}")
+    say(f"Handle: {cfg['handle']}")
+    say(f"URL: https://{cfg['hostname']}/mcp")
+    say(f"Device token: {'stored' if store.read_bytes('device-token') else 'MISSING'} (not shown)")
+    pem = store.read_bytes(CERT)
+    if pem and C.available():
+        info = C.cert_info(pem)
+        say(f"Certificate: valid until {info['not_after']:%Y-%m-%d %H:%M} UTC "
+            f"({C.days_left(info):.0f} days; renews 30 days before)"
+            + (" [Let's Encrypt STAGING]" if cfg.get("staging") else ""))
+    else:
+        say("Certificate: none yet (flowstate relay renew)")
+    st = store.status()
+    fresh = st.get("updated") and time.time() - st["updated"] < STATUS_FRESH_SECONDS
+    if fresh:
+        say(f"Tunnel: {st.get('tunnel')} {st.get('detail') or ''}".rstrip()
+            + f" (agent pid {st.get('pid')}, local port {st.get('port')})")
+    else:
+        say("Tunnel: not running" + (f" (last seen {_when(st.get('updated'))})" if st.get("updated") else ""))
+    if st.get("cert_error"):
+        say(f"Last certificate problem: {st['cert_error']}")
+    ctd = store.ct()
+    if ctd.get("last_attempt"):
+        say(f"CT check: last {_when(ctd.get('last_check'))}, "
+            f"{ctd.get('certificates', 0)} certificate(s) seen"
+            + (f"; last attempt failed: {ctd['error']}" if ctd.get("error") else ""))
+    else:
+        say("CT check: not run yet (flowstate relay ct-check)")
+    alerts = active_alerts(ctd)
+    for al in alerts:
+        say(f"!! WARNING: certificate crt.sh id {al['crtsh_id']} for {', '.join(al['names'])} "
+            f"(issuer {al['issuer']}, from {al['not_before'][:10]}) was NOT made with this "
+            f"computer's key. Someone else can impersonate your relay address. Check "
+            f"https://crt.sh/?id={al['crtsh_id']}, run `flowstate relay disable`, and contact "
+            f"support. If you know it is yours: flowstate relay ct-ack --id {al['crtsh_id']}")
+    from .. import remote_auth as RA
+    if not RA.AuthStore().has_passphrase():
+        say("Owner passphrase: NOT set; apps can't be approved (flowstate remote passphrase)")
+    return 2 if alerts else 0
+
+
+def cmd_enable(a) -> int:
+    store = _store()
+    store.set_enabled(True)
+    say("Relay turned on. Start it with: flowstate relay run")
+    return 0
+
+
+def cmd_disable(a) -> int:
+    store = _store()
+    store.set_enabled(False)
+    say("Relay turned off. A running `flowstate relay run` stops within a few seconds. Your "
+        "enrollment and keys are kept (flowstate relay forget deletes them).")
+    return 0
+
+
+def cmd_forget(a) -> int:
+    store = _store()
+    if not store.root.exists():
+        say("Nothing to forget: the relay was never set up here.")
+        return 0
+    if not a.yes:
+        ans = input(f"Delete the relay device token, keys and certificate in {store.root}? "
+                    f"Type 'forget' to confirm: ")
+        if ans.strip() != "forget":
+            say("Nothing deleted.")
+            return 1
+    gone = store.forget()
+    say(f"Deleted: {', '.join(gone) or 'nothing'}. A running relay stops within a few seconds. "
+        f"The handle stays reserved at the relay until you remove it in your account.")
+    return 0
+
+
+def cmd_ct_check(a) -> int:
+    from . import ct
+    from .store import active_alerts
+    store = _store()
+    r = ct.run_check(store)
+    if r.get("error"):
+        say(f"CT check could not finish: {r['error']}")
+    alerts = active_alerts(r)
+    if alerts:
+        say(f"!! {len(alerts)} certificate(s) for {r['hostname']} use a key that is not this "
+            f"computer's. See: flowstate relay status")
+        return 2
+    say(f"CT check: {r['certificates']} certificate(s) for {r['hostname']}, all made with this "
+        f"computer's key." if not r.get("error") else "No mismatches found so far.")
+    return 1 if r.get("error") else 0
+
+
+def cmd_ct_ack(a) -> int:
+    from . import ct
+    ok = ct.acknowledge(_store(), a.id)
+    say(f"Alert for crt.sh id {a.id} acknowledged." if ok else f"No open alert for crt.sh id {a.id}.")
+    return 0 if ok else 1
+
+
+CHAT_ON = ("AIs connected through the relay can approve and reject review items in the chat "
+           "when they quote you (except deletes and turning review off while approvals are on, "
+           "and \"did you say this?\" checks: those stay yours alone).")
+CHAT_OFF = ("AIs connected through the relay can't approve or reject review items; they tell "
+            "you to decide on your phone instead, from your saved review link (the default). "
+            "Apps on this computer are not affected.")
+
+
+def cmd_chat_approvals(a) -> int:
+    """May an AI on the relay approve / reject review items in the chat? Off by default.
+    Turning it on asks for `y` in your own terminal (an AI's shell has none); off needs nothing.
+    There is no tool for it, so an AI can't switch it on through FlowState."""
+    from .. import approvals
+    from .. import server as S
+    from ..cli_review import _db, open_terminal
+    db = _db(a)
+    S.init_backend(db)   # migrations first (019 holds the settings)
+    S.backend.tracker = None
+    if S.backend.error:
+        say(f"FAILED: FlowState database unavailable: {S.backend.error}")
+        return 1
+    if a.state is None:
+        on = approvals.relay_chat_on(db)
+        say(f"Chat approvals through the relay are {'on' if on else 'off'}. "
+            + (CHAT_ON if on else CHAT_OFF))
+        say("Change it: flowstate relay chat-approvals on|off")
+        return 0
+    if a.state == "on" and not approvals.relay_chat_on(db):
+        tty = open_terminal()
+        if tty is None:
+            say("Refused: turning chat approvals on asks you to confirm in a terminal, and there "
+                "is none here (piped input doesn't count). Run it yourself in a terminal window.")
+            return 2
+        try:
+            if tty.ask("Let AIs connected through the relay approve and reject review items in "
+                       "the chat? Type y to confirm: ").lower() not in ("y", "yes"):
+                say("Not confirmed; nothing changed.")
+                return 1
+        finally:
+            tty.close()
+    try:
+        res = approvals.set_relay_chat(db, a.state == "on")
+    except approvals.ApprovalError as e:
+        say(f"FAILED: {e}")
+        return 1
+    say(f"Chat approvals through the relay are now {res['now']}. "
+        + (CHAT_ON if res["now"] == "on" else CHAT_OFF))
+    return 0
+
+
+# ---------------------------------------------------------------- parser
+def register(sub) -> None:
+    p = sub.add_parser("relay", help="optional relay: reach this FlowState from cloud AIs "
+                                     "(end-to-end TLS; off by default)")
+    rs = p.add_subparsers(dest="relay_action", required=True)
+    q = rs.add_parser("enroll", help="exchange a one-time code for a handle and device token")
+    q.add_argument("--code", required=True)
+    q.add_argument("--staging", action="store_true", help="use Let's Encrypt staging (testing)")
+    q.add_argument("--skip-cert", action="store_true", help="don't request the certificate now")
+    q.set_defaults(fn=_guard(cmd_enroll))
+    q = rs.add_parser("run", help="run the relay agent (with FlowState's public listener)")
+    q.add_argument("--db")
+    q.add_argument("--port", type=int, default=8768, help="local listener port (127.0.0.1)")
+    q.set_defaults(fn=_guard(cmd_run))
+    q = rs.add_parser("status", help="handle, URL, certificate, tunnel, CT check")
+    q.set_defaults(fn=_guard(cmd_status))
+    q = rs.add_parser("renew", help="obtain / renew the certificate now if needed")
+    q.add_argument("--force", action="store_true")
+    g = q.add_mutually_exclusive_group()
+    g.add_argument("--staging", action="store_true", help="switch to Let's Encrypt staging")
+    g.add_argument("--production", action="store_true", help="switch to Let's Encrypt production")
+    q.set_defaults(fn=_guard(cmd_renew))
+    rs.add_parser("enable", help="turn the relay back on").set_defaults(fn=_guard(cmd_enable))
+    rs.add_parser("disable", help="turn the relay off (keeps keys)").set_defaults(fn=_guard(cmd_disable))
+    q = rs.add_parser("forget", help="delete the device token, keys and certificate")
+    q.add_argument("--yes", action="store_true", help="don't ask")
+    q.set_defaults(fn=_guard(cmd_forget))
+    rs.add_parser("ct-check", help="check Certificate Transparency now").set_defaults(fn=_guard(cmd_ct_check))
+    q = rs.add_parser("ct-ack", help="acknowledge a CT alert you have checked")
+    q.add_argument("--id", type=int, required=True)
+    q.set_defaults(fn=_guard(cmd_ct_ack))
+    q = rs.add_parser("chat-approvals", help="may AIs on the relay approve / reject review items "
+                                             "in the chat? (default off: phone only)")
+    q.add_argument("state", nargs="?", choices=["on", "off"], help="omit to show the setting")
+    q.add_argument("--db")
+    q.set_defaults(fn=_guard(cmd_chat_approvals))
+
+
+def _guard(fn):
+    def run(a) -> int:
+        from . import domain_warning
+        warn = domain_warning()
+        if warn:
+            print(warn, file=sys.stderr, flush=True)
+        try:
+            return fn(a)
+        except RelayError as e:
+            say(f"Relay: {e}")
+            return 1
+    return run

flowstate/relay/crypto.py

@@ -0,0 +1,137 @@
+"""Key and certificate helpers for the relay. Uses the `cryptography` package, imported only
+here and only when a relay command runs (it is not a declared FlowState dependency yet; today
+it arrives with `mcp` via `pyjwt[crypto]`). Without it the relay commands say so and the rest
+of FlowState is unaffected.
+
+Every private key is generated on this computer and only ever written to an owner-only file.
+"""
+
+import base64
+import hashlib
+import json
+from datetime import datetime, timezone
+from typing import Optional
+
+from . import RelayError
+
+
+def b64u(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode().rstrip("=")
+
+
+def _lib():
+    try:
+        from cryptography import x509
+        from cryptography.hazmat.primitives import hashes, serialization
+        from cryptography.hazmat.primitives.asymmetric import ec
+        from cryptography.hazmat.primitives.asymmetric.utils import decode_dss_signature
+        from cryptography.x509.oid import NameOID
+    except ImportError as e:  # pragma: no cover - depends on the environment
+        raise RelayError("the relay needs the Python package 'cryptography' "
+                         "(not installed in this environment)") from e
+    return x509, hashes, serialization, ec, decode_dss_signature, NameOID
+
+
+def available() -> bool:
+    try:
+        _lib()
+        return True
+    except RelayError:
+        return False
+
+
+# ---------------------------------------------------------------- keys
+def new_key_pem() -> bytes:
+    """A fresh ECDSA P-256 private key, PKCS#8 PEM (unencrypted; the file is 0600)."""
+    _, _, ser, ec, _, _ = _lib()
+    key = ec.generate_private_key(ec.SECP256R1())
+    return key.private_bytes(ser.Encoding.PEM, ser.PrivateFormat.PKCS8, ser.NoEncryption())
+
+
+def load_key(pem: bytes):
+    _, _, ser, ec, _, _ = _lib()
+    key = ser.load_pem_private_key(pem, password=None)
+    if not isinstance(key, ec.EllipticCurvePrivateKey) or key.curve.name != "secp256r1":
+        raise RelayError("relay key is not an ECDSA P-256 key")
+    return key
+
+
+def spki_sha256(public_key) -> str:
+    """Hex SHA-256 of the DER SubjectPublicKeyInfo (what the CT watch compares)."""
+    _, _, ser, _, _, _ = _lib()
+    der = public_key.public_bytes(ser.Encoding.DER, ser.PublicFormat.SubjectPublicKeyInfo)
+    return hashlib.sha256(der).hexdigest()
+
+
+def key_spki_sha256(pem: bytes) -> str:
+    return spki_sha256(load_key(pem).public_key())
+
+
+# ---------------------------------------------------------------- JWS (ACME)
+def jwk(key) -> dict:
+    nums = key.public_key().public_numbers()
+    return {"crv": "P-256", "kty": "EC", "x": b64u(nums.x.to_bytes(32, "big")),
+            "y": b64u(nums.y.to_bytes(32, "big"))}
+
+
+def jwk_thumbprint(key) -> str:
+    """RFC 7638 thumbprint: SHA-256 over the required members in lexicographic order."""
+    j = jwk(key)
+    canon = json.dumps({k: j[k] for k in ("crv", "kty", "x", "y")}, separators=(",", ":"))
+    return b64u(hashlib.sha256(canon.encode()).digest())
+
+
+def sign_es256(key, data: bytes) -> bytes:
+    """ES256 JWS signature: raw r || s, 32 bytes each (RFC 7518 3.4)."""
+    _, hashes, _, ec, decode_dss, _ = _lib()
+    r, s = decode_dss(key.sign(data, ec.ECDSA(hashes.SHA256())))
+    return r.to_bytes(32, "big") + s.to_bytes(32, "big")
+
+
+def csr_der(key, hostname: str) -> bytes:
+    x509, hashes, ser, _, _, NameOID = _lib()
+    csr = (x509.CertificateSigningRequestBuilder()
+           .subject_name(x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, hostname)]))
+           .add_extension(x509.SubjectAlternativeName([x509.DNSName(hostname)]), critical=False)
+           .sign(key, hashes.SHA256()))
+    return csr.public_bytes(ser.Encoding.DER)
+
+
+# ---------------------------------------------------------------- certificates
+def _names(cert) -> list:
+    x509 = _lib()[0]
+    try:
+        san = cert.extensions.get_extension_for_class(x509.SubjectAlternativeName).value
+        return [n.lower() for n in san.get_values_for_type(x509.DNSName)]
+    except x509.ExtensionNotFound:
+        return []
+
+
+def cert_info(pem: bytes) -> dict:
+    """First certificate of a PEM chain (or one DER certificate): names, expiry, issuer and
+    key fingerprint."""
+    x509 = _lib()[0]
+    try:
+        cert = (x509.load_pem_x509_certificate(pem) if b"-----BEGIN" in pem
+                else x509.load_der_x509_certificate(pem))
+    except ValueError as e:
+        raise RelayError(f"not a PEM certificate ({e})") from e
+    return {"names": _names(cert), "not_after": cert.not_valid_after_utc,
+            "not_before": cert.not_valid_before_utc, "issuer": cert.issuer.rfc4514_string(),
+            "serial": format(cert.serial_number, "x"), "spki_sha256": spki_sha256(cert.public_key())}
+
+
+def days_left(info: dict, now: Optional[datetime] = None) -> float:
+    now = now or datetime.now(timezone.utc)
+    return (info["not_after"] - now).total_seconds() / 86400
+
+
+def covers(pattern: str, hostname: str) -> bool:
+    """Does a certificate name (possibly `*.parent`) cover `hostname`?"""
+    pattern, hostname = pattern.lower().rstrip("."), hostname.lower().rstrip(".")
+    if pattern == hostname:
+        return True
+    if pattern.startswith("*."):
+        head, _, rest = hostname.partition(".")
+        return bool(head) and rest == pattern[2:]
+    return False

flowstate/relay/ct.py

@@ -0,0 +1,118 @@
+"""Certificate Transparency watch.
+
+Every publicly trusted certificate is logged in CT. Once a day the agent asks crt.sh for
+every certificate that covers this computer's relay hostname (exact name and the
+`*.fsmcp.com` wildcard), downloads each new one and compares its public key with
+the local key(s). A certificate made with any other key means someone else (for example
+whoever controls the relay's DNS) got a certificate for the hostname and could read relay
+traffic: it is logged as an ERROR, kept in ct.json and shown at the top of `start_here` and
+in `flowstate relay status` until the user acknowledges it.
+
+Only the hostname is sent to crt.sh, with a plain "flowstate" user agent (no version). Like
+any web request it also shows crt.sh this computer's IP address; the privacy policy says so.
+"""
+
+import json
+import logging
+import time
+from typing import Callable, Optional
+from urllib.parse import quote
+
+from . import HOST_SUFFIX, RelayError
+from . import crypto as C
+from .api import http_request
+
+log = logging.getLogger("flowstate.relay.ct")
+
+CRT_SH = "https://crt.sh/"
+CHECK_EVERY = 24 * 3600
+MAX_FETCH = 50  # certificates downloaded per run (be polite to crt.sh)
+
+
+def _fetch(url: str) -> bytes:
+    status, _, body = http_request("GET", url, headers={"Accept": "*/*", "User-Agent": "flowstate"},
+                                   timeout=60)
+    if status != 200:
+        raise RelayError(f"crt.sh answered {status}")
+    return body
+
+
+def queries(hostname: str) -> list:
+    return [hostname, f"*.{HOST_SUFFIX}"]
+
+
+def check(hostname: str, known_spki: list, previous: Optional[dict] = None,
+          fetch: Callable[[str], bytes] = _fetch, now: Optional[float] = None) -> dict:
+    """One CT pass. Returns the new ct.json content (previous alerts are kept)."""
+    prev = previous or {}
+    seen = {str(k): v for k, v in (prev.get("seen") or {}).items()}
+    alerts = list(prev.get("alerts") or [])
+    out = {"hostname": hostname, "last_attempt": int(now or time.time()), "seen": seen,
+           "alerts": alerts, "last_check": prev.get("last_check"), "error": None,
+           "certificates": prev.get("certificates", 0)}
+    try:
+        entries = {}
+        for q in queries(hostname):
+            data = json.loads(fetch(f"{CRT_SH}?q={quote(q)}&output=json") or b"[]")
+            for e in data if isinstance(data, list) else []:
+                names = str(e.get("name_value", "")).split()
+                if e.get("id") is not None and any(C.covers(n, hostname) for n in names):
+                    entries[str(e["id"])] = e
+        fetched = 0
+        for cid, e in sorted(entries.items(), key=lambda kv: int(kv[0])):
+            if cid in seen:
+                continue
+            if fetched >= MAX_FETCH:
+                break
+            fetched += 1
+            info = C.cert_info(fetch(f"{CRT_SH}?d={quote(cid)}"))
+            if not any(C.covers(n, hostname) for n in info["names"]):
+                seen[cid] = "other-name"
+                continue
+            if info["spki_sha256"] in known_spki:
+                seen[cid] = "ok"
+                continue
+            seen[cid] = "ALERT"
+            alert = {"crtsh_id": int(cid), "issuer": info["issuer"], "names": info["names"],
+                     "not_before": info["not_before"].isoformat(),
+                     "not_after": info["not_after"].isoformat(),
+                     "spki_sha256": info["spki_sha256"], "found_at": out["last_attempt"]}
+            alerts.append(alert)
+            log.error("RELAY SECURITY WARNING: certificate crt.sh id %s for %s (%s) uses a key "
+                      "that is not this computer's. Someone else obtained a certificate for "
+                      "your relay hostname. Run `flowstate relay disable` and check "
+                      "https://crt.sh/?id=%s", cid, hostname, ", ".join(info["names"]), cid)
+        out["certificates"] = len(entries)
+        out["last_check"] = out["last_attempt"]
+    except (RelayError, ValueError, KeyError, TypeError) as e:
+        out["error"] = f"{type(e).__name__}: {str(e)[:200]}"
+        log.warning("CT check for %s could not finish: %s", hostname, out["error"])
+    out["ok"] = not any(not a.get("acknowledged") for a in alerts)
+    return out
+
+
+def run_check(store, fetch: Callable[[str], bytes] = _fetch) -> dict:
+    cfg = store.config()
+    if not cfg.get("hostname"):
+        raise RelayError("the relay is not set up")
+    result = check(cfg["hostname"], list(cfg.get("known_spki") or []), store.ct(), fetch)
+    store.save_ct(result)
+    return result
+
+
+def due(store, now: Optional[float] = None) -> bool:
+    last = store.ct().get("last_attempt") or 0
+    return (now or time.time()) - last >= CHECK_EVERY
+
+
+def acknowledge(store, crtsh_id: int) -> bool:
+    data = store.ct()
+    hit = False
+    for a in data.get("alerts") or []:
+        if a.get("crtsh_id") == crtsh_id and not a.get("acknowledged"):
+            a["acknowledged"] = int(time.time())
+            hit = True
+    if hit:
+        data["ok"] = not any(not a.get("acknowledged") for a in data["alerts"])
+        store.save_ct(data)
+    return hit