sourcelock 0.1.0__py3-none-any.whl

hc_source/guard.py

@@ -0,0 +1,877 @@
+"""Zero-PHI guard.
+
+Every tool call passes through :func:`assert_public_params` before any upstream
+request is made and before anything is logged. The guard's job is narrow and
+adversarial: refuse anything shaped like a patient record.
+
+**What this is, honestly.** A structural, best-effort refusal of patient-shaped
+input. It is NOT a HIPAA compliance control, not a certification, and not a
+guarantee that PHI cannot reach this process. It raises the cost of an accident
+-- a pasted HL7 segment, a CSV column that turned out to hold MRNs, an agent
+that decided a patient name was a search term -- and it will not stop a
+determined sender. Treat a clean scan as "nothing patient-shaped was detected",
+never as "this input contains no PHI". The receipt says ``PHI_NOT_EXPECTED``
+for exactly that reason: it is a statement of design intent, not a finding.
+
+Design rules that matter to adapter authors:
+
+* The guard runs on the RAW parameter mapping, before pydantic validation, so
+  patient-shaped input is refused even when it would have been dropped anyway.
+* Rejection messages never echo the offending value -- the whole point is that
+  the value must not reach a log line. They name the path and the detector.
+* Detection is structural (FHIR/X12/HL7v2 envelopes, SSN and MBI patterns,
+  DOB+name combinations, patient-record field names), not a guess about content.
+* Every budget is a REFUSAL when exceeded, never a silent pass. A guard that
+  gives up quietly is worse than no guard.
+
+Where the line sits, and why
+----------------------------
+Two shipped tools take genuinely free text. ``leie.candidate_search`` takes a
+person's NAME -- that is the entire tool -- and ``coverage.search_documents``
+takes clinical prose like "excision of malignant skin lesions". So:
+
+* an ambiguous-but-plausible value PASSES: a bare surname, a clinical phrase, a
+  date on its own, an NPI;
+* a structured patient-record SHAPE does not: a name next to an SSN, an HL7
+  segment header, an MBI, a DOB beside a name, a FHIR object.
+
+Field NAMES are matched on token boundaries, never as bare substrings. Bare
+substring matching refuses "geographic" (contains "phi"), "adobe" and
+"endobronchial" (contain "dob"), and "outpatient" (contains "patient") -- all of
+which are ordinary product input. The two corpora in ``tests/test_guard_bypass.py``
+and ``tests/test_guard_must_pass.py`` are the executable form of this paragraph;
+change one and you must change the other.
+
+Known evasion classes NOT closed
+--------------------------------
+Stated plainly because honest limits beat silent gaps:
+
+* **Semantic-only PHI.** "the patient in room 4 who came in Tuesday" has no
+  structural marker. Nothing here will catch it.
+* **A single unstructured name or address.** Refusing those would break
+  ``leie.candidate_search``, whose purpose is to search by name. A name alone is
+  accepted by design.
+* **Integer-typed values.** The guard scans string leaves. A caller invoking the
+  Python API with ``{"contractor_id": 123456789}`` as an int is not scanned for
+  SSN shape; over the CLI and MCP everything arrives as a string and is.
+* **Encryption and unknown encodings.** Base64 and percent-encoding are decoded
+  and rescanned to a bounded depth; anything encrypted, compressed, or in an
+  encoding we do not probe passes as opaque bytes.
+* **Free-text identifiers that are not SSN/MBI-shaped.** Local chart numbers,
+  payer-specific member ids and account numbers have no universal shape.
+* **Homoglyph coverage is partial.** A confusables table for the common Cyrillic
+  and Greek Latin-lookalikes is applied; it is not the full Unicode set.
+
+Operator escape hatch
+---------------------
+``HC_SOURCE_GUARD_ALLOW`` takes a comma-separated list of detector codes
+(e.g. ``SSN_PATTERN,MBI_PATTERN``) that :func:`assert_public_params` will not
+refuse on. It exists so a false positive is a config change rather than an
+abandoned pipeline. It suppresses named detectors only -- never the whole guard
+-- and :func:`scan_for_phi` itself is never silenced, so audits and tests always
+see the truth.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import os
+import re
+import unicodedata
+from typing import Any, Iterable, Mapping
+from urllib.parse import unquote
+
+__all__ = [
+    "GUARD_ALLOW_ENV",
+    "PHI_NON_CLAIM",
+    "PHIRejected",
+    "ParamsRejected",
+    "REDACTED",
+    "allowed_detectors",
+    "assert_public_params",
+    "normalize_for_matching",
+    "redact_input",
+    "safe_label",
+    "safe_location",
+    "safe_tool_name",
+    "safe_validation_message",
+    "safe_validation_reasons",
+    "scan_for_phi",
+]
+
+PHI_NON_CLAIM = "PHI_NOT_EXPECTED: this tool accepts only public typed parameters."
+
+GUARD_ALLOW_ENV = "HC_SOURCE_GUARD_ALLOW"
+
+MAX_DEPTH = 12
+MAX_SERIALIZED_BYTES = 64 * 1024
+
+#: Work budgets. Exceeding any of these is a refusal, not a pass -- an input
+#: large or convoluted enough to exhaust the guard is by definition not "a small
+#: typed public parameter".
+MAX_NODES = 4096
+MAX_DECODE_DEPTH = 4
+MAX_EMBEDDED_CANDIDATES = 8
+MAX_ENCODED_RUNS = 4
+MIN_ENCODED_RUN = 12  # 'MTIzLTQ1LTY3ODk=' (a base64 SSN) is 15 chars of payload
+
+
+# ---------------------------------------------------------------------------
+# Normalisation
+# ---------------------------------------------------------------------------
+#
+# Round-1 finding C3: `123-45-6789` was caught but `123.45.6789`, `123–45–6789`
+# (en dash), `123 45 6789` (NBSP) and `123-<ZWSP>45-6789` all walked past,
+# because the pattern hard-coded ASCII hyphen and space. Matching a normalised
+# copy is the fix that generalises; adding one more separator to one more regex
+# is the fix that does not.
+
+_ZERO_WIDTH = dict.fromkeys(
+    [
+        0x00AD,  # soft hyphen
+        0x200B,  # zero width space
+        0x200C,  # zero width non-joiner
+        0x200D,  # zero width joiner
+        0x2060,  # word joiner
+        0xFEFF,  # zero width no-break space
+    ]
+)
+
+#: Latin lookalikes from the Cyrillic and Greek blocks. Partial by design; see
+#: the module docstring's list of limits.
+_CONFUSABLES = str.maketrans(
+    {
+        "а": "a", "е": "e", "о": "o", "р": "p", "с": "c",
+        "у": "y", "х": "x", "ѕ": "s", "і": "i", "ј": "j",
+        "ԁ": "d", "һ": "h", "ӏ": "l", "м": "m", "т": "t",
+        "в": "b", "н": "h", "к": "k", "А": "A", "Е": "E",
+        "О": "O", "Р": "P", "С": "C", "Х": "X", "Ѕ": "S",
+        "І": "I", "М": "M", "Т": "T", "В": "B", "Н": "H",
+        "К": "K", "ο": "o", "α": "a", "ρ": "p", "ν": "v",
+        "τ": "t", "ι": "i", "κ": "k", "μ": "u", "χ": "x",
+        "Α": "A", "Β": "B", "Ε": "E", "Η": "H", "Ι": "I",
+        "Κ": "K", "Μ": "M", "Ν": "N", "Ο": "O", "Ρ": "P",
+        "Τ": "T", "Χ": "X",
+    }
+)
+
+#: Every dash and space variant folded onto the ASCII pair the patterns use.
+_SEPARATORS = str.maketrans(
+    {
+        "‐": "-", "‑": "-", "‒": "-", "–": "-", "—": "-",
+        "―": "-", "−": "-", "﹘": "-", "﹣": "-", "－": "-",
+        " ": " ", " ": " ", " ": " ", " ": " ", " ": " ",
+        " ": " ", " ": " ", " ": " ", " ": " ", " ": " ",
+        " ": " ", " ": " ", " ": " ", " ": " ", " ": " ",
+        "　": " ",
+    }
+)
+
+
+def normalize_for_matching(value: str) -> str:
+    """NFKC, strip zero-width, fold homoglyphs and separator variants.
+
+    Applied to a COPY used only for matching. The original value is never
+    altered and never echoed.
+    """
+    text = unicodedata.normalize("NFKC", value)
+    text = text.translate(_ZERO_WIDTH)
+    text = text.translate(_CONFUSABLES)
+    return text.translate(_SEPARATORS)
+
+
+# ---------------------------------------------------------------------------
+# Detectors
+# ---------------------------------------------------------------------------
+
+_FHIR_PATIENT_RESOURCES = {
+    "Patient",
+    "Bundle",
+    "Coverage",
+    "Claim",
+    "ClaimResponse",
+    "ExplanationOfBenefit",
+    "Encounter",
+    "Observation",
+    "Condition",
+    "MedicationRequest",
+    "DocumentReference",
+    "RelatedPerson",
+    "Person",
+}
+
+#: FHIR field names that are distinctive on their own...
+_FHIR_STRONG_KEYS = {
+    "resourcetype", "birthdate", "gender", "telecom", "maritalstatus",
+    "given", "family", "deceasedboolean", "multiplebirthboolean",
+    "managingorganization",
+}
+#: ...and ones that only mean something in company.
+_FHIR_WEAK_KEYS = {"name", "identifier", "address", "subject", "patient", "contact"}
+
+# SSN: separated (any dialect, post-normalisation) or a bare nine-digit run.
+# The bare-run rule is a deliberate over-block: no shipped parameter legitimately
+# carries a nine-digit string (an NPI is ten, a MAC contractor id is five), and
+# an SSN typed without separators was the single most common bypass in round 1.
+_SSN_SEPARATED_RE = re.compile(r"\b\d{3}[-. ]\d{2}[-. ]\d{4}\b")
+_SSN_BARE_RE = re.compile(r"(?<!\d)\d{9}(?!\d)")
+
+# Medicare Beneficiary Identifier: 11 characters, C-A-AN-N-A-AN-N-A-A-N-N, where
+# A excludes S, L, O, I, B and Z (CMS drops them to avoid digit confusion) and
+# the first character is 1-9. Hyphens are allowed where CMS prints them.
+_MBI_ALPHA = "ACDEFGHJKMNPQRTUVWXY"
+_MBI_RE = re.compile(
+    rf"(?<![A-Za-z0-9])"
+    rf"[1-9][{_MBI_ALPHA}][{_MBI_ALPHA}0-9]\d-?"
+    rf"[{_MBI_ALPHA}][{_MBI_ALPHA}0-9]\d-?"
+    rf"[{_MBI_ALPHA}][{_MBI_ALPHA}]\d\d"
+    rf"(?![A-Za-z0-9])",
+    re.IGNORECASE,
+)
+
+# X12 and HL7 v2: a SINGLE strong marker now trips. Requiring two ANDed markers
+# was finding C3's biggest hole -- a bare `PID|` segment is the most common leak
+# shape there is, and it carried name, MRN, DOB, sex and address.
+_X12_RE = re.compile(
+    r"(?:\bISA\*|\bGS\*(HC|HB|HI|HN|HP|HR|HS)\b|\bST\*(837|835|270|271|276|277|278)\b"
+    r"|\bNM1\*IL\*|\bDMG\*D8\*)"
+)
+_HL7V2_SEGMENTS = "MSH|PID|PV1|OBX|OBR|NK1|IN1|IN2|DG1|EVN|ORC|AL1|GT1"
+_HL7V2_RE = re.compile(rf"(?:\A|[\r\n\s>:])(?:{_HL7V2_SEGMENTS})\|")
+
+# Free-text patient record: a patient-record word AND a date, together.
+_FREE_TEXT_SUBJECT_TOKENS = {
+    "mrn", "dob", "ssn", "patient", "member", "beneficiary", "subscriber", "hicn", "mbi",
+}
+_FREE_TEXT_DATE_RE = re.compile(
+    r"(?<!\d)(?:\d{1,2}[/.-]\d{1,2}[/.-]\d{2,4}|\d{4}[/.-]\d{1,2}[/.-]\d{1,2}|\d{8})(?!\d)"
+)
+
+# Field-name patterns. Matched against TOKENS of a parameter key, never as bare
+# substrings: "geographic" contains "phi", "adobe" contains "dob", "outpatient"
+# contains "patient", and all three are ordinary product input.
+_STRONG_KEY_TOKENS: dict[str, str] = {
+    "ssn": "SSN",
+    "mrn": "MEDICAL_RECORD_NUMBER",
+    "phi": "PHI",
+    "dob": "DOB",
+    "birthdate": "DOB",
+    "birthday": "DOB",
+    "birthyear": "DOB",
+    "yob": "DOB",
+    "patient": "PATIENT_RECORD",
+    "hicn": "MEMBER_IDENTIFIER",
+    "mbi": "MEMBER_IDENTIFIER",
+}
+#: Token PAIRS. "beneficiary notice of noncoverage" is a real CMS document type,
+#: so "beneficiary" alone must not refuse -- "beneficiary_id" must.
+_SUBJECT_TOKENS = {"patient", "member", "subscriber", "beneficiary", "enrollee", "insured"}
+_IDENTIFIER_TOKENS = {
+    "id", "ids", "identifier", "number", "num", "no", "nbr", "mrn", "ssn", "dob",
+    "name", "record", "chart", "account", "acct",
+}
+_PAIR_LABELS = {
+    "patient": "PATIENT_RECORD",
+    "member": "MEMBER_IDENTIFIER",
+    "subscriber": "MEMBER_IDENTIFIER",
+    "beneficiary": "MEMBER_IDENTIFIER",
+    "enrollee": "MEMBER_IDENTIFIER",
+    "insured": "MEMBER_IDENTIFIER",
+}
+#: Multi-word field names, matched against the key's token SEQUENCE.
+_PHRASE_KEY_TOKENS: tuple[tuple[tuple[str, ...], str], ...] = (
+    (("social", "security"), "SSN"),
+    (("medical", "record"), "MEDICAL_RECORD_NUMBER"),
+    (("date", "of", "birth"), "DOB"),
+    (("birth", "date"), "DOB"),
+    (("birth", "year"), "DOB"),
+    (("date", "of", "service"), "PATIENT_RECORD"),
+)
+
+_DOB_TOKENS = {"dob", "birthdate", "birthday", "birthyear", "yob"}
+_DOB_PHRASES = ((("date", "of", "birth"),), (("birth", "date"),), (("birth", "year"),))
+_NAME_TOKENS = {"firstname", "lastname", "familyname", "givenname", "middlename", "fullname"}
+_NAME_PHRASES = (
+    ("first", "name"),
+    ("last", "name"),
+    ("family", "name"),
+    ("given", "name"),
+    ("middle", "name"),
+    ("full", "name"),
+    ("patient", "name"),
+)
+_DATE_VALUE_RE = re.compile(r"^\s*(\d{4}-\d{2}-\d{2}|\d{2}/\d{2}/\d{4}|\d{4})\s*$")
+
+_TOKEN_SPLIT_RE = re.compile(r"[^a-z0-9]+")
+_CAMEL_SPLIT_RE = re.compile(r"(?<=[a-z0-9])(?=[A-Z])")
+_BASE64_RUN_RE = re.compile(r"[A-Za-z0-9+/]{%d,}={0,2}" % MIN_ENCODED_RUN)
+_PERCENT_RE = re.compile(r"%[0-9A-Fa-f]{2}")
+
+
+def _key_tokens(key: str) -> tuple[list[str], str]:
+    """Return ``(tokens, condensed)`` for a parameter key.
+
+    ``tokens`` splits on separators and camelCase humps, so ``patientMRN`` and
+    ``patient_mrn`` both yield ``["patient", "mrn"]`` while ``outpatient`` yields
+    ``["outpatient"]`` and is left alone. ``condensed`` is the alphanumeric-only
+    form, used only to defeat separator obfuscation (``p_a_t_i_e_n_t``).
+    """
+    normalized = normalize_for_matching(key)
+    humped = _CAMEL_SPLIT_RE.sub(" ", normalized).lower()
+    tokens = [t for t in _TOKEN_SPLIT_RE.split(humped) if t]
+    condensed = "".join(ch for ch in normalized.lower() if ch.isalnum())
+    return tokens, condensed
+
+
+class PHIRejected(ValueError):
+    """Raised when a tool call's parameters look like a patient record."""
+
+    def __init__(self, tool: str, reasons: list[str]) -> None:
+        self.tool = tool
+        self.reasons = list(reasons)
+        joined = "; ".join(self.reasons)
+        super().__init__(
+            f"SourceLock refused the call to {tool!r}: parameters look like protected health "
+            f"information. {PHI_NON_CLAIM} Reasons: {joined}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Value-free parameter rejection
+# ---------------------------------------------------------------------------
+#
+# Round-1 finding C1: a custom pydantic validator that quoted its input put the
+# raw value into ``error["msg"]``, and every consumer built its message from
+# ``msg``. The consumers were value-blind by assumption, not by construction.
+#
+# The fix is a boundary, not a patch: ``ToolSpec.invoke`` converts every
+# ``ValidationError`` into a :class:`ParamsRejected` whose text is built from
+# ``loc`` plus a message that has been scrubbed of the input value. Nothing
+# downstream -- CLI, MCP, or a library consumer that simply does ``str(exc)`` --
+# can reach the raw value, and a future adapter that quotes its input is
+# scrubbed on the way out instead of reopening the hole.
+
+REDACTED = "[value withheld]"
+
+#: Below this length a value is not distinctive enough to be worth redacting,
+#: and redacting it would mangle ordinary words in rule text ("ncd", "lcd").
+_MIN_REDACTABLE = 3
+
+#: A label safe to print back at whoever sent it: an ordinary identifier. Field
+#: names, tool names and pydantic error locations all take this shape, and
+#: nothing that carries data does.
+_SAFE_LABEL_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_]{0,39}$")
+
+#: Six digits in a row. Long enough to exclude every field name and version
+#: suffix this product uses, short enough to catch anything that identifies a
+#: person or an entity.
+_LONG_DIGIT_RUN_RE = re.compile(r"\d{6,}")
+
+
+def safe_label(text: str, index: int | None = None) -> str:
+    """Echo ``text`` only if it is an identifier; otherwise a positional stand-in.
+
+    Round-1 closed the value-echo hole for parameter VALUES. Keys, tool names and
+    pydantic ``loc`` entries were still printed verbatim -- and every one of them
+    is caller-controlled. ``{"123-45-6789": "x"}`` against a model with
+    ``extra='forbid'`` produced a rejection reason and a pydantic ``loc`` that
+    both quoted the SSN: the refusal itself became the leak.
+
+    An identifier-shaped label is kept because a caller genuinely needs to know
+    WHICH parameter was wrong. Anything else is data wearing a name, and it is
+    replaced with its position.
+    """
+    if _SAFE_LABEL_RE.match(text) and not _looks_like_an_identifier_value(text):
+        return text
+    return f"<key #{index}>" if index is not None else "<withheld>"
+
+
+def _looks_like_an_identifier_value(text: str) -> bool:
+    """True when an identifier-shaped string still carries an identifier inside it.
+
+    ``ssn123456789`` passes ``_SAFE_LABEL_RE`` and is still nine digits of
+    somebody's identity. The long-digit-run rule generalises past SSN and MBI:
+    no field name in this product carries six consecutive digits, while every
+    identifier worth withholding does -- SSN, NPI, MBI, a chart number.
+    ``icd10cm_fy2026`` and ``v28`` are unaffected.
+    """
+    normalized = normalize_for_matching(text)
+    return bool(
+        _LONG_DIGIT_RUN_RE.search(normalized)
+        or _SSN_SEPARATED_RE.search(normalized)
+        or _MBI_RE.search(normalized)
+    )
+
+
+#: A route name: ``source.tool``, both halves lowercase slugs. Every shipped
+#: tool matches; nothing that carries data does.
+_TOOL_NAME_RE = re.compile(r"^[a-z][a-z0-9_]{0,31}\.[a-z][a-z0-9_]{0,31}$")
+
+
+def safe_tool_name(name: str) -> str:
+    """Echo a requested tool name only if it is shaped like one.
+
+    An MCP client picks the string, and "no tool named X" reflected X back
+    verbatim -- so a client could get an arbitrary value written into a server
+    log by asking for it as a tool. A real name is useful in the error; anything
+    else tells the caller nothing they did not already know.
+    """
+    return name if _TOOL_NAME_RE.match(name) else "<name withheld>"
+
+
+def safe_location(loc: Any) -> str:
+    """A pydantic ``loc`` tuple rendered without echoing caller-controlled names.
+
+    With ``extra='forbid'`` the ``loc`` of an unexpected-field error IS the key
+    the caller invented, so this is the same hole as :func:`safe_label` in a
+    different coat.
+    """
+    parts = loc if isinstance(loc, (tuple, list)) else (loc,)
+    rendered = [
+        str(p) if isinstance(p, int) else safe_label(str(p), i)
+        for i, p in enumerate(parts)
+    ]
+    return ".".join(rendered) or "<params>"
+
+
+class ParamsRejected(ValueError):
+    """Parameters did not fit a tool's declared model.
+
+    Carries field locations and rule text only. The offending value is never
+    stored on the exception, so no consumer can echo it -- not by printing the
+    exception, not by walking ``errors()``, and not from a traceback (the
+    originating ``ValidationError`` is deliberately not chained).
+    """
+
+    def __init__(self, tool: str, problems: list[tuple[str, str]]) -> None:
+        self.tool = tool
+        self.problems = list(problems)
+        joined = "; ".join(f"{loc}: {msg}" for loc, msg in self.problems) or "invalid parameters"
+        super().__init__(f"{tool}: invalid parameters -- {joined}")
+
+    def errors(self) -> list[dict[str, str]]:
+        """Value-free stand-in for ``ValidationError.errors()``."""
+        return [{"loc": loc, "msg": msg} for loc, msg in self.problems]
+
+
+def _leaf_strings(value: Any, depth: int = 0) -> Iterable[str]:
+    """Yield every string-ish leaf of ``value`` that is worth redacting."""
+    if depth > MAX_DEPTH:
+        return
+    if isinstance(value, str):
+        if len(value) >= _MIN_REDACTABLE:
+            yield value
+    elif isinstance(value, Mapping):
+        for k, v in value.items():
+            yield from _leaf_strings(k, depth + 1)
+            yield from _leaf_strings(v, depth + 1)
+    elif isinstance(value, (list, tuple, set)):
+        for v in value:
+            yield from _leaf_strings(v, depth + 1)
+    elif isinstance(value, (int, float)) and not isinstance(value, bool):
+        text = str(value)
+        if len(text) >= _MIN_REDACTABLE:
+            yield text
+
+
+def redact_input(text: str, value: Any) -> str:
+    """Remove every occurrence of ``value`` (or any of its leaves) from ``text``.
+
+    Case-insensitive, because a value is often upper/lower-cased on its way into
+    a message. Longest leaves first so a nested value is not half-redacted.
+    """
+    leaves = sorted(set(_leaf_strings(value)), key=len, reverse=True)
+    for leaf in leaves:
+        text = re.sub(re.escape(leaf), REDACTED, text, flags=re.IGNORECASE)
+    return text
+
+
+def safe_validation_reasons(exc: Any) -> list[tuple[str, str]]:
+    """Reduce a pydantic ``ValidationError`` to ``(location, rule)`` pairs.
+
+    ``msg`` is used because pydantic's own rule text is genuinely useful ("String
+    should match pattern ..."), but it is scrubbed against ``input`` first: a
+    custom validator is free to quote its value and still cannot leak it.
+    """
+    errors = getattr(exc, "errors", None)
+    if not callable(errors):
+        return [("<params>", type(exc).__name__)]
+    problems: list[tuple[str, str]] = []
+    for error in errors():
+        location = safe_location(error.get("loc", ()))
+        message = str(error.get("msg", "invalid"))
+        if "input" in error:
+            message = redact_input(message, error["input"])
+        problems.append((location, message))
+    return problems
+
+
+def safe_validation_message(exc: Any) -> str:
+    """One line of ``field: rule`` pairs, with no input values in it."""
+    return "; ".join(f"{loc}: {msg}" for loc, msg in safe_validation_reasons(exc)) or (
+        "invalid parameters"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Entry points
+# ---------------------------------------------------------------------------
+
+
+def allowed_detectors() -> set[str]:
+    """Detector codes the operator has chosen to accept, from the environment."""
+    raw = os.environ.get(GUARD_ALLOW_ENV, "")
+    return {part.strip().upper() for part in raw.split(",") if part.strip()}
+
+
+def assert_public_params(params: Mapping[str, Any] | Any, *, tool: str) -> None:
+    """Raise :class:`PHIRejected` unless ``params`` are public typed parameters.
+
+    Honours ``HC_SOURCE_GUARD_ALLOW``: reasons whose detector code appears there
+    are not grounds for refusal. Everything else still is -- suppressing one
+    detector never disables the guard.
+    """
+    reasons = scan_for_phi(params)
+    allowed = allowed_detectors()
+    if allowed:
+        reasons = [r for r in reasons if r.split(":", 1)[0].strip().upper() not in allowed]
+    if reasons:
+        raise PHIRejected(tool, reasons)
+    return None
+
+
+def scan_for_phi(params: Mapping[str, Any] | Any) -> list[str]:
+    """Return a list of reasons ``params`` look patient-shaped (empty == clean).
+
+    A pure detector: never reads the environment, never suppresses anything.
+    The operator allowlist is applied by :func:`assert_public_params`, so this
+    function always tells an auditor the truth.
+
+    Reasons never contain the offending value.
+    """
+    reasons: list[str] = []
+    _check_size(params, reasons)
+    if reasons:
+        return reasons
+
+    budget = _Budget()
+    for path, key, value in _walk(params, reasons, budget=budget):
+        if key is not None:
+            _check_key(key, path, reasons)
+        if isinstance(value, Mapping):
+            _check_dob_name_combo(value, path, reasons)
+        _check_value(value, path, reasons, budget=budget)
+
+    # Stable, de-duplicated order.
+    seen: set[str] = set()
+    unique: list[str] = []
+    for r in reasons:
+        if r not in seen:
+            seen.add(r)
+            unique.append(r)
+    return unique
+
+
+class _Budget:
+    """Shared work counters for one scan. Exhaustion is a refusal, not a pass."""
+
+    def __init__(self) -> None:
+        self.nodes = 0
+        self.exhausted = False
+
+
+def _check_size(params: Any, reasons: list[str]) -> None:
+    try:
+        size = len(json.dumps(params, default=str))
+    except (TypeError, ValueError):
+        return
+    if size > MAX_SERIALIZED_BYTES:
+        reasons.append(
+            f"OVERSIZED_PARAMS: parameters serialize to {size} bytes (limit "
+            f"{MAX_SERIALIZED_BYTES}); SourceLock tools take small typed public parameters, "
+            "not documents"
+        )
+
+
+def _walk(
+    node: Any,
+    reasons: list[str],
+    path: str = "params",
+    depth: int = 0,
+    *,
+    budget: _Budget,
+) -> Iterable[tuple[str, str | None, Any]]:
+    """Iteratively yield ``(path, key, value)`` for every node in the structure."""
+    stack: list[tuple[str, str | None, Any, int]] = [(path, None, node, depth)]
+    while stack:
+        cur_path, cur_key, cur_value, cur_depth = stack.pop()
+        if cur_depth > MAX_DEPTH:
+            reasons.append(
+                f"UNEXPECTED_STRUCTURE: parameters nest deeper than {MAX_DEPTH} levels at "
+                f"{cur_path}; public typed parameters are flat"
+            )
+            continue
+
+        budget.nodes += 1
+        if budget.nodes > MAX_NODES:
+            if not budget.exhausted:
+                budget.exhausted = True
+                reasons.append(
+                    f"UNEXPECTED_STRUCTURE: parameters contain more than {MAX_NODES} values; "
+                    "SourceLock tools take a handful of small typed public parameters, so an "
+                    "input this large is refused rather than partially inspected"
+                )
+            return
+
+        yield cur_path, cur_key, cur_value
+
+        if isinstance(cur_value, Mapping):
+            for i, (k, v) in enumerate(cur_value.items()):
+                # The KEY is caller-controlled too. `{"123-45-6789": "x"}` used
+                # to produce a refusal reason that quoted the SSN back in the
+                # path -- the guard refusing a value by repeating it.
+                stack.append(
+                    (f"{cur_path}.{safe_label(str(k), i)}", str(k), v, cur_depth + 1)
+                )
+        elif isinstance(cur_value, (list, tuple, set)):
+            for i, v in enumerate(cur_value):
+                stack.append((f"{cur_path}[{i}]", None, v, cur_depth + 1))
+
+
+def _check_key(key: str, path: str, reasons: list[str]) -> None:
+    tokens, condensed = _key_tokens(key)
+    token_set = set(tokens)
+
+    for token, label in _STRONG_KEY_TOKENS.items():
+        if token in token_set:
+            reasons.append(
+                f"PATIENT_SHAPED_KEY: parameter at {path} is named after a patient-record "
+                f"field ({label})"
+            )
+
+    for subject in _SUBJECT_TOKENS & token_set:
+        if token_set & _IDENTIFIER_TOKENS:
+            reasons.append(
+                f"PATIENT_SHAPED_KEY: parameter at {path} names a person plus an identifier "
+                f"({_PAIR_LABELS[subject]})"
+            )
+
+    joined = " ".join(tokens)
+    for phrase, label in _PHRASE_KEY_TOKENS:
+        if " ".join(phrase) in joined:
+            reasons.append(
+                f"PATIENT_SHAPED_KEY: parameter at {path} is named after a patient-record "
+                f"field ({label})"
+            )
+
+    # Separator obfuscation only: `p_a_t_i_e_n_t` splits into single characters,
+    # which no ordinary field name does. Condensing `outpatient_setting` would
+    # false-positive, so the condensed form is consulted for THIS shape alone.
+    if sum(1 for t in tokens if len(t) == 1) >= 3:
+        for token, label in _STRONG_KEY_TOKENS.items():
+            if token in condensed:
+                reasons.append(
+                    f"OBFUSCATED_KEY: parameter at {path} spells a patient-record field name "
+                    f"through separators ({label})"
+                )
+
+
+def _check_value(value: Any, path: str, reasons: list[str], *, budget: _Budget) -> None:
+    if isinstance(value, Mapping):
+        _check_fhir_object(value, path, reasons)
+        return
+
+    if not isinstance(value, str):
+        return
+
+    _scan_text(value, path, reasons, budget=budget, decode_depth=0)
+
+
+def _check_fhir_object(value: Mapping[str, Any], path: str, reasons: list[str]) -> None:
+    """FHIR detection that does not depend on ``resourceType``.
+
+    Finding C3: an object carrying ``name`` and ``gender`` but no
+    ``resourceType`` was invisible, because detection keyed entirely off that
+    one field.
+    """
+    resource = value.get("resourceType")
+    if isinstance(resource, str):
+        reasons.append(
+            f"FHIR_RESOURCE: object at {path} carries resourceType "
+            f"{'(patient-shaped)' if resource in _FHIR_PATIENT_RESOURCES else '(FHIR)'}; "
+            "SourceLock does not accept FHIR payloads"
+        )
+        return
+
+    keys = {str(k).lower() for k in value}
+    strong = keys & _FHIR_STRONG_KEYS
+    weak = keys & _FHIR_WEAK_KEYS
+    if strong and len(strong | weak) >= 2:
+        reasons.append(
+            f"PATIENT_RESOURCE_SHAPE: object at {path} carries person-record fields "
+            "(demographics plus an identifier or name) without declaring a resourceType; "
+            "SourceLock does not accept patient records"
+        )
+
+
+def _scan_text(value: str, path: str, reasons: list[str], *, budget: _Budget, decode_depth: int) -> None:
+    """Run every text detector, then probe encodings and embedded structures."""
+    text = normalize_for_matching(value)
+
+    if _SSN_SEPARATED_RE.search(text) or _SSN_BARE_RE.search(text):
+        reasons.append(f"SSN_PATTERN: value at {path} contains an SSN-shaped token")
+
+    if _MBI_RE.search(text):
+        reasons.append(
+            f"MBI_PATTERN: value at {path} contains a Medicare Beneficiary Identifier-shaped "
+            "token (11 characters in the CMS C-A-AN-N-A-AN-N-A-A-N-N form)"
+        )
+
+    if _X12_RE.search(text):
+        reasons.append(f"X12_ENVELOPE: value at {path} contains an X12 segment marker")
+
+    if _HL7V2_RE.search(text):
+        reasons.append(f"HL7V2_MESSAGE: value at {path} contains an HL7 v2 segment header")
+
+    _check_free_text_record(text, path, reasons)
+
+    if decode_depth >= MAX_DECODE_DEPTH:
+        # Do not give up quietly: if there is still something decodable here, the
+        # input is more encoded than any public typed parameter has cause to be.
+        if _looks_encoded(text):
+            reasons.append(
+                f"ENCODED_PAYLOAD: value at {path} is encoded more than {MAX_DECODE_DEPTH} "
+                "layers deep; SourceLock takes small typed public parameters, not encoded "
+                "documents"
+            )
+        return
+
+    _scan_embedded_json(value, path, reasons, budget=budget, decode_depth=decode_depth)
+    _scan_encoded(value, path, reasons, budget=budget, decode_depth=decode_depth)
+
+
+def _check_free_text_record(text: str, path: str, reasons: list[str]) -> None:
+    """A patient-record word next to a date is a patient record in prose.
+
+    ``MRN 88213 DOE JOHN DOB 01/02/1980`` had no structural envelope at all and
+    walked straight through round 1. Either half alone passes: "dobutamine" is
+    not "dob", and a date on its own is just a date.
+    """
+    tokens = {t for t in _TOKEN_SPLIT_RE.split(text.lower()) if t}
+    if not (tokens & _FREE_TEXT_SUBJECT_TOKENS):
+        return
+    if _FREE_TEXT_DATE_RE.search(text):
+        reasons.append(
+            f"PATIENT_RECORD_TEXT: value at {path} combines a patient-record term "
+            "(MRN/DOB/SSN/patient/member) with a date, which identifies an individual"
+        )
+
+
+def _looks_encoded(text: str) -> bool:
+    return bool(_PERCENT_RE.search(text)) or bool(_BASE64_RUN_RE.search(text))
+
+
+def _scan_embedded_json(
+    value: str, path: str, reasons: list[str], *, budget: _Budget, decode_depth: int
+) -> None:
+    """Parse JSON found ANYWHERE in the string, not only at position 0.
+
+    Finding C3: ``"payload: " + <FHIR Bundle>`` passed because the scan only
+    fired when the first non-space character was ``{`` or ``[``.
+    """
+    if len(value) > MAX_SERIALIZED_BYTES:
+        return
+
+    stripped = value.strip()
+    if stripped[:1] == '"':
+        # Double-encoded JSON: the outer parse yields a string that is itself
+        # JSON. One `json.loads` and a rescan, rather than one and done.
+        try:
+            inner = json.loads(stripped)
+        except (ValueError, RecursionError):
+            inner = None
+        if isinstance(inner, str):
+            _scan_text(inner, path, reasons, budget=budget, decode_depth=decode_depth + 1)
+            return
+
+    decoder = json.JSONDecoder()
+    candidates = 0
+    for match in re.finditer(r"[{\[]", value):
+        candidates += 1
+        if candidates > MAX_EMBEDDED_CANDIDATES:
+            return
+        try:
+            parsed, _ = decoder.raw_decode(value, match.start())
+        except (ValueError, RecursionError):
+            continue
+        if not isinstance(parsed, (Mapping, list)):
+            continue
+        for reason in scan_for_phi(parsed):
+            reasons.append(f"EMBEDDED_JSON at {path}: {reason}")
+        return
+
+
+def _scan_encoded(
+    value: str, path: str, reasons: list[str], *, budget: _Budget, decode_depth: int
+) -> None:
+    """Decode base64 and percent-encoded runs and rescan what comes out.
+
+    Only findings from the DECODED text are reported, so a name that happens to
+    look like base64 costs one decode attempt and nothing else.
+    """
+    if _PERCENT_RE.search(value):
+        decoded = unquote(value)
+        if decoded != value:
+            _scan_text(decoded, path, reasons, budget=budget, decode_depth=decode_depth + 1)
+
+    runs = 0
+    for match in _BASE64_RUN_RE.finditer(value):
+        runs += 1
+        if runs > MAX_ENCODED_RUNS:
+            return
+        blob = match.group(0)
+        try:
+            raw = base64.b64decode(blob + "=" * (-len(blob) % 4), validate=True)
+        except (binascii.Error, ValueError):
+            continue
+        try:
+            decoded = raw.decode("utf-8")
+        except UnicodeDecodeError:
+            continue
+        if not decoded.isprintable() and not any(c in decoded for c in "\r\n\t"):
+            continue
+        _scan_text(decoded, path, reasons, budget=budget, decode_depth=decode_depth + 1)
+
+
+def _check_dob_name_combo(params: Mapping[str, Any], path: str, reasons: list[str]) -> None:
+    """A date of birth beside a personal name identifies an individual.
+
+    Runs on every mapping the walk reaches, not just the top level, so it also
+    fires inside decoded or embedded JSON.
+    """
+    has_dob = False
+    has_name = False
+    for key, value in params.items():
+        tokens, _ = _key_tokens(str(key))
+        token_set = set(tokens)
+        joined = " ".join(tokens)
+
+        if token_set & _DOB_TOKENS or any(
+            " ".join(phrase) in joined for group in _DOB_PHRASES for phrase in group
+        ):
+            has_dob = True
+        elif isinstance(value, str) and _DATE_VALUE_RE.match(value) and (
+            "birth" in token_set or "dob" in token_set
+        ):
+            has_dob = True
+
+        if token_set & _NAME_TOKENS or any(" ".join(p) in joined for p in _NAME_PHRASES):
+            has_name = True
+
+    if has_dob and has_name:
+        reasons.append(
+            f"DOB_PLUS_NAME: parameters at {path} combine a date-of-birth field with a "
+            "personal name field, which identifies an individual"
+        )