incognito-sql 0.0.5a1__py3-none-any.whl

incognito_sql/__init__.py

@@ -0,0 +1,10 @@
+"""Pseudonymizing MCP server for LLM access to databases with personal data."""
+
+import logging
+
+__version__ = "0.0.0"
+
+# sqlglot logs unparsable SQL verbatim (with its literals); keep it off stderr.
+_sqlglot_log = logging.getLogger("sqlglot")
+_sqlglot_log.addHandler(logging.NullHandler())
+_sqlglot_log.propagate = False

incognito_sql/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m incognito_sql`: the same command line as `incognito-sql`."""
+
+from incognito_sql.cli import main
+
+raise SystemExit(main())

incognito_sql/assess/__init__.py

@@ -0,0 +1,6 @@
+"""`assess`: the disclosure levels of the operator's own database, under its profile.
+
+The oracles of ``incognito_sql.levels`` ask a gateway opened on a copy of the operator's
+declaration, as a server is asked; the truth they judge by is read from the database
+directly. The report holds counts and column names, never a value.
+"""

incognito_sql/assess/command.py

@@ -0,0 +1,47 @@
+"""`incognito-sql assess`: its arguments, the run, the report and the exit code."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from incognito_sql.assess.model import Source
+from incognito_sql.assess.report import as_json, as_text, broken
+from incognito_sql.assess.run import assess
+from incognito_sql.core.config import Declaration
+
+EXIT_BROKEN = 1
+EXIT_FAILED = 2
+
+
+def add_assess_parser(commands: "argparse._SubParsersAction[argparse.ArgumentParser]") -> None:
+    """Add `assess` and its options to the command line."""
+    command = commands.add_parser(
+        "assess", help="judge the disclosure levels of this database under its profile"
+    )
+    command.add_argument("--config", type=Path, required=True, help="the service's declaration")
+    command.add_argument("--env-file", type=Path, help="KEY=VALUE secrets for unset variables")
+    command.add_argument("--targets", type=int, default=3, help="values probed per column")
+    command.add_argument(
+        "--capacity", action="store_true", help="also measure with the literal budget lifted"
+    )
+    command.add_argument("--json", action="store_true", help="print the report as JSON")
+    command.add_argument(
+        "--fail-on", choices=["breaks"], help="exit 1 when a column breaks its profile's claim"
+    )
+
+
+def run_assess(args: argparse.Namespace, decl: Declaration, dsn: str, key: bytes) -> int:
+    """Assess, print the report on stdout, return the exit code.
+
+    A failure is named by its type alone: a database error quotes its query's
+    parameters, and the series' probes are made from the values.
+    """
+    try:
+        result = assess(
+            Source(args.config, decl, dsn, key), count=args.targets, capacity=args.capacity
+        )
+    except Exception as exc:  # noqa: BLE001 -- any failure: never its message
+        sys.stderr.write(f"incognito-sql: assess failed: {type(exc).__name__}\n")
+        return EXIT_FAILED
+    sys.stdout.write((as_json(result) if args.json else as_text(result)) + "\n")
+    return EXIT_BROKEN if args.fail_on == "breaks" and broken(result) else 0

incognito_sql/assess/model.py

@@ -0,0 +1,87 @@
+"""What an assessment reads and what it found, column by column."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from incognito_sql.core.config import Declaration, Limits
+from incognito_sql.levels.infer import Budgets, Inference
+from incognito_sql.levels.verdict import Leaks, verdict
+
+
+def budgets_of(limits: Limits) -> Budgets:
+    """Return the literal and probe budgets of ``limits`` and their window."""
+    return Budgets(limits.literal_budget, limits.probe_budget, limits.literal_window_s)
+
+
+@dataclass(frozen=True)
+class Source:
+    """The service's settings: its declaration file and what it was read into."""
+
+    config: Path
+    decl: Declaration
+    dsn: str
+    key: bytes
+
+
+@dataclass
+class ColumnLevels:
+    """What the oracles saw on one column: cuts that showed it, facts the series read."""
+
+    table: str
+    column: str
+    profile: str
+    opened: frozenset[str]  # L3 channels the profile declares open
+    cuts: int = 0
+    whole: int = 0  # cuts that showed a value whole
+    parts: int = 0  # cuts that showed a part of one
+    measure: bool = False  # the budgets lifted: values read whole are their capacity
+    budgets: Budgets = field(default_factory=lambda: budgets_of(Limits()))  # the config's own
+    inference: Inference = field(default_factory=Inference)
+
+    @property
+    def name(self) -> str:
+        """Return ``table.column``."""
+        return f"{self.table}.{self.column}"
+
+    def verdict(self) -> str:
+        """Return whether the column keeps its profile's claim, and what it broke."""
+        leaks = Leaks(
+            shown=bool(self.whole),
+            read_whole=bool(self.inference.whole) and not self.measure,
+            parts=bool(self.parts),
+            inferred=frozenset(self.inference.open_channels()),
+        )
+        found = verdict(leaks, "L3", self.opened)
+        if found == "holds" and not any(self.inference.targets.values()):
+            return "holds cuts; no value to probe by a series"
+        return found
+
+
+@dataclass
+class HiddenColumn:
+    """A column the declaration does not name: every cut of it must be refused."""
+
+    table: str
+    column: str
+    cuts: int = 0
+    refused: int = 0
+
+    @property
+    def name(self) -> str:
+        """Return ``table.column``."""
+        return f"{self.table}.{self.column}"
+
+    def verdict(self) -> str:
+        """Return ``holds`` when every cut was refused."""
+        return (
+            "holds" if self.refused == self.cuts else f"breaks: {self.cuts - self.refused} answered"
+        )
+
+
+@dataclass
+class Assessment:
+    """Every identifier column under the default budget, and with it lifted if asked."""
+
+    columns: list[ColumnLevels]
+    capacity: list[ColumnLevels]
+    hidden: list[HiddenColumn] = field(default_factory=list)

incognito_sql/assess/report.py

@@ -0,0 +1,66 @@
+"""The assessment as the operator reads it: counts per column and level, never a value."""
+
+import json
+
+from incognito_sql.assess.model import Assessment, ColumnLevels, HiddenColumn
+from incognito_sql.levels.infer import CHANNELS, HOURS_LEGEND, WHOLE
+
+
+def _row(c: ColumnLevels) -> dict[str, object]:
+    series = c.inference
+    row: dict[str, object] = {
+        "column": c.name,
+        "profile": c.profile,
+        "L1 cuts": f"{c.whole}/{c.cuts}",
+        "L1 series": f"{series.whole}/{series.targets['prefix']}",
+        "L2 cuts": f"{c.parts}/{c.cuts}",
+        **{f"L3 {ch}": series.share(ch) for ch in CHANNELS},
+        "price whole": series.price(WHOLE),
+    }
+    if c.measure:  # what the config's own budget would make the attacker wait
+        row["hours whole"] = series.hours(WHOLE, c.budgets)
+    row["verdict"] = c.verdict()
+    return row
+
+
+def _hidden(c: HiddenColumn) -> dict[str, object]:
+    return {"column": c.name, "hidden: refused": f"{c.refused}/{c.cuts}", "verdict": c.verdict()}
+
+
+def as_dict(result: Assessment) -> dict[str, list[dict[str, object]]]:
+    """Return the report as data: identifier columns, hidden ones, then the budget lifted."""
+    return {
+        "columns": [_row(c) for c in result.columns],
+        "hidden": [_hidden(c) for c in result.hidden],
+        "capacity": [_row(c) for c in result.capacity],
+    }
+
+
+def as_json(result: Assessment) -> str:
+    """Return the report as JSON."""
+    return json.dumps(as_dict(result), ensure_ascii=False, indent=2)
+
+
+def as_text(result: Assessment) -> str:
+    """Return the report as Markdown tables: verdicts first, capacity after."""
+    parts = []
+    for title, rows in as_dict(result).items():
+        if not rows:
+            continue
+        head = list(rows[0])
+        lines = [f"## {title}", "", "| " + " | ".join(head) + " |", "|---" * len(head) + "|"]
+        lines += ["| " + " | ".join(str(r[k]) for k in head) + " |" for r in rows]
+        if "hours whole" in head:
+            lines += ["", HOURS_LEGEND]
+        parts.append("\n".join(lines))
+    return "\n\n".join(parts) or "no identifier column of an entity table to assess"
+
+
+def broken(result: Assessment) -> bool:
+    """Tell whether a column breaks its profile's claim, with the budget lifted too.
+
+    Lifted, a closed channel inferred is a hole of the policy the budget hid.
+    """
+    verdicts = [c.verdict() for c in [*result.columns, *result.capacity]]
+    verdicts += [c.verdict() for c in result.hidden]
+    return any(v.startswith("breaks") for v in verdicts)

incognito_sql/assess/run.py

@@ -0,0 +1,146 @@
+"""Run the oracles on each identifier column against a gateway of its own.
+
+The gateway is opened on a copy of the declaration in a temporary directory: its own
+literal budget, journal and tokens, so the assessment never spends the budget live
+agents share nor raises its alarm. Cuts and series ask it as one connection, as one
+agent session would; a second pass with the literal budget lifted measures what each
+channel carries.
+"""
+
+import json
+import tempfile
+import uuid
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+import yaml
+from sqlalchemy.engine import Engine
+
+from incognito_sql.assess.model import Assessment, ColumnLevels, HiddenColumn, Source, budgets_of
+from incognito_sql.assess.truth import (
+    DbTruth,
+    hidden_columns,
+    identifier_columns,
+    targets,
+    values,
+)
+from incognito_sql.core.config import load_declaration
+from incognito_sql.core.config.model import column_operations, column_profile
+from incognito_sql.core.config.protection import opens
+from incognito_sql.core.db import make_engine
+from incognito_sql.core.pipeline import Gateway
+from incognito_sql.levels import asker as budgets
+from incognito_sql.levels.asker import Ask, Asker, Reply
+from incognito_sql.levels.cuts import cuts
+from incognito_sql.levels.fragment import Fragments
+from incognito_sql.levels.infer import CHANNELS
+from incognito_sql.levels.oracle import Oracle
+from incognito_sql.levels.partial import Visible, shown_in_part
+from incognito_sql.levels.series import run_series
+from incognito_sql.wiring import open_gateway
+
+VALUES_CAP = 100_000  # distinct values of a column looked for in the answers
+_LIFTED = 1_000_000
+
+
+def assess(source: Source, *, count: int, capacity: bool) -> Assessment:
+    """Assess every identifier column of an entity table on ``count`` targets each."""
+    decl = source.decl
+    engine = make_engine(
+        source.dsn, decl.dialect, statement_timeout_ms=decl.limits.statement_timeout_ms
+    )
+    try:
+        hidden = [HiddenColumn(t, c) for t, c in hidden_columns(engine, decl)]
+        with _opened(source, lifted=False) as (gateway, connection):
+            for closed in hidden:
+                for _, sql in cuts(closed.table, closed.column, decl.dialect):
+                    closed.cuts += 1
+                    closed.refused += "error" in gateway.query(sql, connection)
+        columns = list(identifier_columns(decl))
+        held = [_column(source, engine, c, count, lifted=False) for c in columns]
+        lifted = (
+            [_column(source, engine, c, count, lifted=True) for c in columns] if capacity else []
+        )
+    finally:
+        engine.dispose()
+    return Assessment(held, lifted, hidden)
+
+
+@contextmanager
+def _opened(source: Source, *, lifted: bool) -> Iterator[tuple[Gateway, str]]:
+    """Open a gateway on a copy of the config: its own budget, audit log and tokens."""
+    with tempfile.TemporaryDirectory(prefix="incognito-assess-") as tmp:
+        copy = _copy(source.config, Path(tmp), lifted=lifted)
+        gateway = open_gateway(copy, load_declaration(copy), source.dsn, source.key)
+        try:
+            yield gateway, uuid.uuid4().hex
+        finally:
+            gateway.close()
+
+
+def _column(
+    source: Source, engine: Engine, column: tuple[str, str, str], count: int, *, lifted: bool
+) -> ColumnLevels:
+    """Assess one column against a gateway of its own: no column spends another's budget."""
+    decl = source.decl
+    table, name, key = column
+    profile = column_profile(decl, table, name)
+    leaks = opens(column_operations(decl, table, name))
+    opened = frozenset(str(leak).removeprefix("L3 ") for leak in leaks)
+    own = budgets_of(decl.limits)
+    levels = ColumnLevels(table, name, profile, opened, measure=lifted, budgets=own)
+    tool, series = (
+        (budgets.CAPACITY_TOOL, budgets.CAPACITY_SERIES)
+        if lifted
+        else (budgets.TOOL_BUDGET, budgets.SERIES_BUDGET)
+    )
+    with _opened(source, lifted=lifted) as (gateway, connection):
+        if not lifted:
+            _cut(gateway, connection, values(engine, table, name, VALUES_CAP), levels, decl.dialect)
+        asker = Asker(_asking(gateway, connection), tool, series, decl.dialect)
+        for target in targets(engine, table, name, key, count):
+            for channel in CHANNELS:
+                levels.inference.add(run_series(asker, DbTruth(engine), target, channel))
+    levels.inference.settle()
+    return levels
+
+
+def _cut(
+    gateway: Gateway, connection: str, hidden: list[object], levels: ColumnLevels, dialect: str
+) -> None:
+    oracle, fragments = Oracle(hidden), Fragments(hidden)
+    for _, sql in cuts(levels.table, levels.column, dialect):
+        answer = gateway.query(sql, connection)
+        levels.cuts += 1
+        if "error" in answer:
+            continue
+        text = json.dumps(answer, ensure_ascii=False, default=str)
+        whole = oracle.found(text)
+        levels.whole += bool(whole)
+        levels.parts += bool(shown_in_part(fragments.found(text), whole, (Visible([sql]),)))
+
+
+def _asking(gateway: Gateway, connection: str) -> Ask:
+    def ask(sql: str) -> Reply:
+        answer, spend = gateway.ask(sql, connection)
+        spent = (spend.literals, spend.probes)
+        if "error" in answer:
+            return Reply(answered=False, spend=spent)
+        rows = answer.get("rows")
+        text = json.dumps(answer, default=str)
+        rows = rows if isinstance(rows, list) else None
+        return Reply(answered=True, rows=rows, text=text, spend=spent)
+
+    return ask
+
+
+def _copy(config: Path, into: Path, *, lifted: bool) -> Path:
+    data = yaml.safe_load(config.read_text(encoding="utf-8"))
+    limits = data.setdefault("limits", {})
+    limits["query_rate"] = _LIFTED  # a brake on a search, not a bound on what it learns
+    if lifted:  # both: a budget left in place would cut the series and its cost short
+        limits["literal_budget"] = limits["probe_budget"] = _LIFTED
+    out = into / "assess.yaml"
+    out.write_text(yaml.safe_dump(data, sort_keys=False, allow_unicode=True), encoding="utf-8")
+    return out

incognito_sql/assess/truth.py

@@ -0,0 +1,104 @@
+"""The database read directly: targets of the series, values to look for, and truth.
+
+Read by the service's DSN through a read-only engine, never through the protection.
+Queries are built with SQLAlchemy, which writes them in the database's dialect.
+"""
+
+from collections.abc import Iterator
+
+import sqlalchemy as sa
+from sqlalchemy.engine import Engine
+
+from incognito_sql.core.config import ColumnClass, Declaration
+from incognito_sql.core.sql.catalog import reflect
+from incognito_sql.levels.cuts import ROWS
+from incognito_sql.levels.target import MIN_TARGET, Target
+
+_POOL = 1000  # rows a target is chosen among
+
+
+def _table(name: str, *columns: str) -> sa.TableClause:
+    return sa.table(name, *(sa.column(c) for c in columns))
+
+
+class DbTruth:
+    """The truth of the series: the database compares and finds values itself."""
+
+    def __init__(self, engine: Engine) -> None:
+        """Read through ``engine``."""
+        self._engine = engine
+
+    def below(self, target: Target, probe: object) -> bool:
+        """Tell whether the target's value sorts below ``probe`` in the database."""
+        t = _table(target.table, target.key, target.column)
+        query = (
+            sa.select(sa.func.count())
+            .select_from(t)
+            .where(t.c[target.key] == target.row, t.c[target.column] < probe)
+        )
+        with self._engine.connect() as con:
+            return bool(con.execute(query).scalar())
+
+    def holds(self, target: Target, value: object) -> bool:
+        """Tell whether a row of the target's column holds ``value``."""
+        t = _table(target.table, target.column)
+        query = sa.select(sa.literal(1)).select_from(t).where(t.c[target.column] == value).limit(1)
+        with self._engine.connect() as con:
+            return con.execute(query).first() is not None
+
+
+def identifier_columns(decl: Declaration) -> Iterator[tuple[str, str, str]]:
+    """Yield (table, column, key) of every identifier column of an entity table."""
+    keys = {e.table: e.pk for e in decl.entities}
+    for table in sorted(decl.columns):
+        for column, cls in sorted(decl.columns[table].items()):
+            if cls is ColumnClass.IDENTIFIER and table in keys:
+                yield table, column, keys[table]
+
+
+def hidden_columns(engine: Engine, decl: Declaration) -> list[tuple[str, str]]:
+    """Return (table, column) of every database column the declaration does not name.
+
+    The tables and views are those the server reflects, named as it resolves them.
+    """
+    out = []
+    for table, columns in sorted(reflect(engine, decl.dialect).columns.items()):
+        named = decl.columns.get(table.lower(), {})
+        out += [(table, c) for c in sorted(columns) if c.lower() not in named]
+    return out
+
+
+def targets(engine: Engine, table: str, column: str, key: str, count: int) -> list[Target]:
+    """Return up to ``count`` targets of one column, rows spread over its first ones."""
+    t = _table(table, key, column)
+    query = sa.select(t.c[key], t.c[column]).where(t.c[column].is_not(None)).order_by(t.c[key])
+    with engine.connect() as con:
+        rows = con.execute(query.limit(_POOL)).all()
+    pool = [
+        Target(table, key, row, column, value)
+        for row, value in rows
+        if isinstance(value, str | int | float) and len(str(value)) >= MIN_TARGET
+    ]
+    step = max(1, len(pool) // max(count, 1))
+    return pool[::step][:count]
+
+
+def values(engine: Engine, table: str, column: str, cap: int) -> list[object]:
+    """Return what is looked for in a column's answers.
+
+    Up to ``cap`` distinct values, and those a cut can show whatever the sample holds:
+    the first rows and the extremes.
+    """
+    t = _table(table, column)
+    present = t.c[column].is_not(None)
+    queries = [
+        sa.select(t.c[column]).where(present).distinct().limit(cap),
+        sa.select(t.c[column]).where(present).limit(ROWS),
+        sa.select(sa.func.min(t.c[column])).where(present),
+        sa.select(sa.func.max(t.c[column])).where(present),
+    ]
+    found: dict[object, None] = {}
+    with engine.connect() as con:
+        for query in queries:
+            found.update((v, None) for (v,) in con.execute(query) if v is not None)
+    return list(found)

incognito_sql/audit_command.py

@@ -0,0 +1,50 @@
+"""`incognito-sql audit verify`: check the audit log's chain with the service's key."""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from incognito_sql.core.audit_chain import Anchor
+from incognito_sql.core.audit_verify import verify
+from incognito_sql.core.tokens.crypto import Cipher, load_key
+from incognito_sql.envfile import EnvFileError, load_env_file
+from incognito_sql.wiring import audit_path, store_path
+
+EXIT_BROKEN, EXIT_UNREADABLE = 1, 2
+
+
+def add_audit_parser(commands: "argparse._SubParsersAction[argparse.ArgumentParser]") -> None:
+    """Add `audit verify` to the command line."""
+    audit = commands.add_parser("audit", help="the audit log")
+    actions = audit.add_subparsers(dest="audit_command", required=True)
+    check = actions.add_parser("verify", help="check that no line was edited, removed or added")
+    check.add_argument("--config", type=Path, required=True, help="the service's declaration")
+    check.add_argument("--env-file", type=Path, help="KEY=VALUE secrets for unset variables")
+
+
+def run_audit(args: argparse.Namespace) -> int:
+    """Check the chain; print what was checked and the first break; return the exit code."""
+    log, store = audit_path(args.config), store_path(args.config)
+    try:
+        if args.env_file is not None:
+            load_env_file(args.env_file, os.environ)
+        cipher = Cipher(load_key())
+        anchor = Anchor(store) if store.exists() else None
+        try:
+            verdict = verify(log, cipher, anchor.get() if anchor else None)
+        finally:
+            if anchor is not None:
+                anchor.close()
+    except (OSError, EnvFileError, RuntimeError, ValueError) as exc:
+        sys.stderr.write(f"incognito-sql: audit verify: {type(exc).__name__}\n")
+        return EXIT_UNREADABLE
+    sys.stdout.write(
+        f"lines: {verdict.lines}; before the chain: {verdict.before_chain}; "
+        f"checked: {verdict.checked}; anchor: {verdict.anchor}\n"
+    )
+    if verdict.holds:
+        sys.stdout.write("the chain holds\n")
+        return 0
+    sys.stdout.write(f"broken: {verdict.broken}\n")
+    return EXIT_BROKEN

incognito_sql/check/__init__.py

@@ -0,0 +1 @@
+"""`incognito-sql check`: try, as the agent's user, what an agent could do around the server."""

incognito_sql/check/clients.py

@@ -0,0 +1,99 @@
+"""MCP client settings this user can read, and the entries that start incognito-sql itself."""
+
+import json
+import re
+import tomllib
+from collections.abc import Iterator, Mapping
+from pathlib import Path
+
+from incognito_sql.check.probes import Finding
+
+_NAMES = ("incognito-sql", "incognito_sql")
+# A value that only names a variable the client fills in: `${env:X}`, `{env:X}`, `${X}`.
+_REFERENCE = re.compile(r"\$?\{(?:env:)?[A-Za-z_][A-Za-z0-9_]*\}")
+
+
+def client_settings(home: Path, cwd: Path, environ: Mapping[str, str]) -> list[tuple[str, Path]]:
+    """Return the MCP settings files of common clients, each with a fixed label.
+
+    A finding names the file by its label: a path built from a variable such as
+    CODEX_HOME may hold anything pasted there, and is not repeated.
+    """
+    codex = environ.get("CODEX_HOME")
+    files = [
+        ("Claude Code project file (.mcp.json)", cwd / ".mcp.json"),
+        ("Cursor project file (.cursor/mcp.json)", cwd / ".cursor" / "mcp.json"),
+        ("OpenCode project file (opencode.json)", cwd / "opencode.json"),
+        ("Claude Code user file (~/.claude.json)", home / ".claude.json"),
+        ("Cursor user file (~/.cursor/mcp.json)", home / ".cursor" / "mcp.json"),
+        (
+            "OpenCode user file (~/.config/opencode/opencode.json)",
+            home / ".config" / "opencode" / "opencode.json",
+        ),
+        ("Codex user file (~/.codex/config.toml)", home / ".codex" / "config.toml"),
+        (
+            "Claude Desktop file (macOS)",
+            home / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json",
+        ),
+        ("Claude Desktop file (Linux)", home / ".config" / "Claude" / "claude_desktop_config.json"),
+    ]
+    if codex:
+        files.append(("Codex file ($CODEX_HOME/config.toml)", Path(codex) / "config.toml"))
+    if "APPDATA" in environ:
+        path = Path(environ["APPDATA"]) / "Claude" / "claude_desktop_config.json"
+        files.append(("Claude Desktop file (Windows)", path))
+    return files
+
+
+def _servers(tree: object) -> Iterator[Mapping[str, object]]:
+    """Yield every server entry at any depth.
+
+    The keys are `mcpServers` (Claude Code nests them per project; Cursor),
+    `mcp_servers` (Codex) and `mcp` (OpenCode).
+    """
+    if isinstance(tree, dict):
+        for key in ("mcpServers", "mcp_servers", "mcp"):
+            servers = tree.get(key)
+            if isinstance(servers, dict):
+                yield from (s for s in servers.values() if isinstance(s, dict))
+        for value in tree.values():
+            yield from _servers(value)
+    elif isinstance(tree, list):
+        for value in tree:
+            yield from _servers(value)
+
+
+def _starts_us(server: Mapping[str, object]) -> bool:
+    command = server.get("command", "")
+    words = list(command) if isinstance(command, list) else [command]  # OpenCode: a list
+    args = server.get("args", [])
+    if isinstance(args, list):
+        words.extend(args)
+    # The script name, or the package run as a module (`python -m incognito_sql`).
+    return any(name in str(word) for word in words for name in _NAMES)
+
+
+def _parsed(path: Path) -> object:
+    text = path.read_text(encoding="utf-8-sig")
+    return tomllib.loads(text) if path.suffix == ".toml" else json.loads(text)
+
+
+def client_findings(files: list[tuple[str, Path]]) -> list[Finding]:
+    """Flag each client entry that runs incognito-sql as this user, with secrets beside it."""
+    found: list[Finding] = []
+    for label, path in files:
+        try:
+            servers = list(_servers(_parsed(path)))
+        except (OSError, ValueError, RecursionError):  # unreadable, not JSON or TOML, too deep
+            continue
+        for server in servers:
+            if not _starts_us(server):
+                continue
+            env = server.get("env", server.get("environment"))  # OpenCode: `environment`
+            what = f"{label} starts incognito-sql as this user"
+            if isinstance(env, dict) and any(
+                not _REFERENCE.fullmatch(str(value)) for value in env.values()
+            ):
+                what += ", with its secrets in the file"
+            found.append(Finding(what, hole=True, fix="run it as a service and connect over HTTP"))
+    return found