sourcelock 0.1.0__py3-none-any.whl

hc_source/manifest.py

@@ -0,0 +1,422 @@
+"""Signed release manifests: prove *which* pins and vendored data a run used.
+
+A manifest is a JSON **envelope** with two top-level keys::
+
+    {"payload": {...}, "signature": {...} | null}
+
+``payload`` captures the current state of the world as this install sees it:
+
+* the lockfile pins (raw sha256 of the file plus the parsed sources), so a
+  customer can check the manifest they received against the ``source-lock.json``
+  they committed;
+* a sha256 for every vendored data file packaged under ``hc_source/data/``;
+* tool versions (sourcelock itself, python, and the load-bearing libraries);
+* ``signed_at``, written by ``sign_envelope``. It lives in the payload rather
+  than beside the signature because a signing time nobody signed is a signing
+  time anyone can edit, and "this was signed before the incident" is precisely
+  what a manifest gets used to claim.
+
+Signing is Ed25519 (via ``cryptography``), computed over the **canonical
+serialization of the payload only**: ``json.dumps(payload, sort_keys=True,
+separators=(",", ":"), ensure_ascii=False).encode("utf-8")``. The envelope file
+itself may be pretty-printed, re-indented, or re-ordered without breaking the
+signature -- only the payload's *content* is covered. The signature block is
+detached in exactly that sense: it lives next to the payload, never inside it.
+
+Trust model: ``verify`` trusts ONLY the public key handed to it (``--key``).
+The fingerprint embedded in the signature block identifies which key was used
+(useful during rotation) but is never itself a verification input.
+
+Keys are PEM: PKCS8 for the private key, SubjectPublicKeyInfo for the public
+key. ``generate_keypair`` writes the private key ``0600`` and refuses to
+overwrite existing files. Private keys never belong in this repository --
+see the ops runbook for storage and rotation.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import platform
+from importlib import metadata
+from pathlib import Path
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+from .lockfile import load_lockfile
+from .schemas import utcnow
+
+__all__ = [
+    "MANIFEST_KIND",
+    "MANIFEST_VERSION",
+    "ManifestError",
+    "SIGNATURE_ALGORITHM",
+    "SIGNING_KEY_ENV",
+    "build_envelope",
+    "build_payload",
+    "canonical_payload_bytes",
+    "generate_keypair",
+    "load_envelope",
+    "load_private_key",
+    "load_public_key",
+    "public_key_fingerprint",
+    "save_envelope",
+    "sign_envelope",
+    "tool_versions",
+    "vendored_data_hashes",
+    "verify_envelope",
+    "verify_lockfile",
+    "verify_vendored_data",
+]
+
+MANIFEST_VERSION = 1
+MANIFEST_KIND = "sourcelock-manifest"
+SIGNATURE_ALGORITHM = "Ed25519"
+#: Environment variable naming the private-key path for ``hc-source manifest sign``.
+SIGNING_KEY_ENV = "HC_SOURCE_SIGNING_KEY"
+
+#: Distributions whose versions are recorded in every manifest.
+_TRACKED_DISTS = ("sourcelock", "httpx", "typer", "rich", "pydantic", "mcp", "cryptography")
+
+_DATA_DIR = Path(__file__).resolve().parent / "data"
+
+
+class ManifestError(Exception):
+    """A manifest envelope, key, or signature is unusable. The message says why."""
+
+
+# ---------------------------------------------------------------------------
+# canonicalization
+# ---------------------------------------------------------------------------
+
+
+def canonical_payload_bytes(payload: dict) -> bytes:
+    """The exact bytes a signature covers. Deterministic for equal payloads."""
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode(
+        "utf-8"
+    )
+
+
+def _sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+# ---------------------------------------------------------------------------
+# payload
+# ---------------------------------------------------------------------------
+
+
+def vendored_data_hashes(data_dir: Path | None = None) -> dict[str, dict]:
+    """sha256 + size for every file packaged under ``hc_source/data/``.
+
+    Keys are POSIX-style paths relative to the data dir, sorted, so the map is
+    byte-stable across platforms. ``__pycache__`` droppings are excluded.
+    """
+    root = Path(data_dir) if data_dir is not None else _DATA_DIR
+    if not root.is_dir():
+        raise ManifestError(f"vendored data directory not found: {root}")
+    out: dict[str, dict] = {}
+    for path in sorted(root.rglob("*")):
+        if not path.is_file() or "__pycache__" in path.parts:
+            continue
+        raw = path.read_bytes()
+        out[path.relative_to(root).as_posix()] = {
+            "sha256": _sha256_bytes(raw),
+            "bytes": len(raw),
+        }
+    return out
+
+
+def tool_versions() -> dict[str, str]:
+    versions: dict[str, str] = {"python": platform.python_version()}
+    for dist in _TRACKED_DISTS:
+        try:
+            versions[dist] = metadata.version(dist)
+        except metadata.PackageNotFoundError:
+            versions[dist] = "not-installed"
+    return versions
+
+
+def build_payload(lock_path: Path) -> dict:
+    """Assemble the manifest payload from a lockfile on disk.
+
+    Raises ``FileNotFoundError`` (with the fix) when the lockfile is absent and
+    ``pydantic.ValidationError`` when it does not parse -- same contract as the
+    rest of the CLI.
+    """
+    lock_path = Path(lock_path)
+    lockfile = load_lockfile(lock_path)  # validates; raises with remediation
+    raw = lock_path.read_bytes()
+    return {
+        "kind": MANIFEST_KIND,
+        "manifest_version": MANIFEST_VERSION,
+        "generated_at": utcnow().isoformat(),
+        "lockfile": {
+            "path": lock_path.name,
+            "sha256": _sha256_bytes(raw),
+            "generated_at": lockfile.generated_at.isoformat(),
+            "sources": {
+                sid: entry.model_dump(mode="json") for sid, entry in lockfile.sources.items()
+            },
+        },
+        "vendored_data": vendored_data_hashes(),
+        "tool_versions": tool_versions(),
+    }
+
+
+def build_envelope(lock_path: Path) -> dict:
+    return {"payload": build_payload(lock_path), "signature": None}
+
+
+# ---------------------------------------------------------------------------
+# envelope io
+# ---------------------------------------------------------------------------
+
+
+def load_envelope(path: Path) -> dict:
+    path = Path(path)
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ManifestError(f"cannot read manifest {path}: {type(exc).__name__}") from exc
+    try:
+        envelope = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ManifestError(f"manifest {path} is not valid JSON: {exc}") from exc
+
+    if not isinstance(envelope, dict) or "payload" not in envelope:
+        raise ManifestError(f"manifest {path} is not an envelope: expected a 'payload' key")
+    payload = envelope["payload"]
+    if not isinstance(payload, dict):
+        raise ManifestError(f"manifest {path}: payload must be an object")
+    if payload.get("kind") != MANIFEST_KIND:
+        raise ManifestError(
+            f"manifest {path}: payload.kind is {payload.get('kind')!r}, expected {MANIFEST_KIND!r}"
+        )
+    if payload.get("manifest_version") != MANIFEST_VERSION:
+        raise ManifestError(
+            f"manifest {path}: manifest_version {payload.get('manifest_version')!r} "
+            f"is not supported (this tool speaks version {MANIFEST_VERSION})"
+        )
+    envelope.setdefault("signature", None)
+    return envelope
+
+
+def save_envelope(envelope: dict, path: Path) -> Path:
+    """Write an envelope pretty-printed. Formatting never affects the signature."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(envelope, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return path
+
+
+# ---------------------------------------------------------------------------
+# keys
+# ---------------------------------------------------------------------------
+
+
+def load_private_key(path: Path) -> Ed25519PrivateKey:
+    path = Path(path)
+    try:
+        raw = path.read_bytes()
+    except OSError as exc:
+        raise ManifestError(f"cannot read private key {path}: {type(exc).__name__}") from exc
+    try:
+        key = serialization.load_pem_private_key(raw, password=None)
+    except (ValueError, TypeError) as exc:
+        raise ManifestError(
+            f"{path} is not a readable unencrypted PEM private key: {exc}"
+        ) from exc
+    if not isinstance(key, Ed25519PrivateKey):
+        raise ManifestError(f"{path} is not an Ed25519 private key ({type(key).__name__})")
+    return key
+
+
+def load_public_key(path: Path) -> Ed25519PublicKey:
+    path = Path(path)
+    try:
+        raw = path.read_bytes()
+    except OSError as exc:
+        raise ManifestError(f"cannot read public key {path}: {type(exc).__name__}") from exc
+    try:
+        key = serialization.load_pem_public_key(raw)
+    except ValueError as exc:
+        raise ManifestError(f"{path} is not a readable PEM public key: {exc}") from exc
+    if not isinstance(key, Ed25519PublicKey):
+        raise ManifestError(f"{path} is not an Ed25519 public key ({type(key).__name__})")
+    return key
+
+
+def public_key_fingerprint(public_key: Ed25519PublicKey) -> str:
+    """sha256 hex over the 32 raw public-key bytes. Identifies a key, proves nothing."""
+    raw = public_key.public_bytes(
+        encoding=serialization.Encoding.Raw, format=serialization.PublicFormat.Raw
+    )
+    return _sha256_bytes(raw)
+
+
+def generate_keypair(out_dir: Path, name: str = "manifest-signing") -> tuple[Path, Path]:
+    """Write ``<name>.key`` (PKCS8 PEM, mode 0600) and ``<name>.pub`` (PEM).
+
+    Refuses to overwrite: rotating a key must be an explicit new name, never a
+    silent replacement of the file a customer's verify step still trusts.
+    """
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    priv_path = out_dir / f"{name}.key"
+    pub_path = out_dir / f"{name}.pub"
+    for existing in (priv_path, pub_path):
+        if existing.exists():
+            raise ManifestError(
+                f"{existing} already exists; pick a new --name instead of overwriting a key"
+            )
+
+    private_key = Ed25519PrivateKey.generate()
+    priv_pem = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    pub_pem = private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+
+    priv_path.touch(mode=0o600)
+    priv_path.write_bytes(priv_pem)
+    priv_path.chmod(0o600)
+    pub_path.write_bytes(pub_pem)
+    return priv_path, pub_path
+
+
+# ---------------------------------------------------------------------------
+# sign / verify
+# ---------------------------------------------------------------------------
+
+
+def sign_envelope(envelope: dict, private_key: Ed25519PrivateKey) -> dict:
+    """Return a new envelope whose signature block covers the payload.
+
+    ``signed_at`` goes INSIDE the payload. It used to sit in the signature block
+    beside the signature itself, where nothing covered it: anyone holding a
+    signed manifest could edit the timestamp and it still verified. A signing
+    time that can be rewritten by the person you are proving something to is not
+    evidence, and "this manifest was signed before the incident" is exactly the
+    claim a manifest gets used for.
+    """
+    payload = envelope.get("payload")
+    if not isinstance(payload, dict):
+        raise ManifestError("envelope has no payload to sign")
+    payload = {**payload, "signed_at": utcnow().isoformat()}
+    signature = private_key.sign(canonical_payload_bytes(payload))
+    return {
+        "payload": payload,
+        "signature": {
+            "algorithm": SIGNATURE_ALGORITHM,
+            "public_key_fingerprint": public_key_fingerprint(private_key.public_key()),
+            "signature_b64": base64.b64encode(signature).decode("ascii"),
+        },
+    }
+
+
+def verify_envelope(envelope: dict, public_key: Ed25519PublicKey) -> None:
+    """Raise :class:`ManifestError` unless the signature verifies with this key.
+
+    The provided key is the only trust anchor. The embedded fingerprint is
+    checked first purely to produce a better error message when the manifest
+    was signed by a *different* key (e.g. after rotation).
+    """
+    payload = envelope.get("payload")
+    if not isinstance(payload, dict):
+        raise ManifestError("envelope has no payload")
+    signature = envelope.get("signature")
+    if not isinstance(signature, dict):
+        raise ManifestError("manifest is unsigned: run `hc-source manifest sign` first")
+
+    algorithm = signature.get("algorithm")
+    if algorithm != SIGNATURE_ALGORITHM:
+        raise ManifestError(
+            f"unsupported signature algorithm {algorithm!r} (expected {SIGNATURE_ALGORITHM!r})"
+        )
+
+    embedded = signature.get("public_key_fingerprint")
+    ours = public_key_fingerprint(public_key)
+    if isinstance(embedded, str) and embedded != ours:
+        raise ManifestError(
+            "manifest was signed by a different key "
+            f"(manifest fingerprint {embedded[:16]}..., verifying key {ours[:16]}...); "
+            "if the signing key was rotated, fetch the current public key"
+        )
+
+    sig_b64 = signature.get("signature_b64")
+    if not isinstance(sig_b64, str):
+        raise ManifestError("signature block has no signature_b64")
+    try:
+        raw_sig = base64.b64decode(sig_b64, validate=True)
+    except (ValueError, TypeError) as exc:
+        raise ManifestError(f"signature_b64 is not valid base64: {exc}") from exc
+
+    try:
+        public_key.verify(raw_sig, canonical_payload_bytes(payload))
+    except InvalidSignature:
+        raise ManifestError(
+            "signature does NOT verify: the payload was modified after signing, "
+            "or it was signed by a different key"
+        ) from None
+
+
+def verify_lockfile(payload: dict, lock_path: Path) -> list[str]:
+    """Compare the payload's lockfile hash to the lockfile at ``lock_path``.
+
+    Without this, a signed manifest proves only that SOME lockfile was signed at
+    some point. It says nothing about the ``source-lock.json`` doctor and the
+    runtime are actually reading, which is the one a customer cares about --
+    "the pins were signed" and "the pins in use were signed" are different
+    claims, and only the second is worth anything in an audit.
+    """
+    recorded = payload.get("lockfile")
+    if not isinstance(recorded, dict) or not isinstance(recorded.get("sha256"), str):
+        return ["payload has no lockfile hash to compare against"]
+    lock_path = Path(lock_path)
+    try:
+        raw = lock_path.read_bytes()
+    except OSError as exc:
+        return [f"{lock_path}: cannot read the lockfile ({type(exc).__name__})"]
+    local = _sha256_bytes(raw)
+    if local != recorded["sha256"]:
+        return [
+            f"{lock_path}: sha256 {local[:16]}... does not match the signed manifest's "
+            f"{recorded['sha256'][:16]}.... The manifest describes a different set of pins "
+            "than the ones this install would check against. Re-run `hc-source manifest "
+            "build` and re-sign, or find out who changed the lockfile."
+        ]
+    return []
+
+
+def verify_vendored_data(payload: dict, data_dir: Path | None = None) -> list[str]:
+    """Compare the payload's vendored-data hashes to this install's files.
+
+    Returns a list of human-readable mismatches (empty means everything
+    matches). This answers "is the data I am running the data that was
+    signed?", which the signature alone cannot.
+    """
+    recorded = payload.get("vendored_data")
+    if not isinstance(recorded, dict):
+        return ["payload has no vendored_data map"]
+    local = vendored_data_hashes(data_dir)
+    problems: list[str] = []
+    for rel, meta in sorted(recorded.items()):
+        if rel not in local:
+            problems.append(f"{rel}: recorded in manifest but missing from this install")
+            continue
+        if not isinstance(meta, dict) or local[rel]["sha256"] != meta.get("sha256"):
+            problems.append(f"{rel}: sha256 differs from the signed manifest")
+    for rel in sorted(set(local) - set(recorded)):
+        problems.append(f"{rel}: present in this install but absent from the signed manifest")
+    return problems

hc_source/mcp_server.py

@@ -0,0 +1,203 @@
+"""MCP server mode: ``hc-source mcp``.
+
+Every discovered tool is served over MCP stdio with the adapter's own parameter
+schema and the same zero-PHI guard the CLI uses, so an agent cannot reach a
+route by a path that skips the guard.
+
+Two notes on the library, both verified against the installed ``mcp`` 2.0.0
+(the version is pinned in pyproject.toml because this module depends on the
+API shape):
+
+* As of ``mcp`` 2.0 the FastMCP class is named ``MCPServer``; ``FastMCP`` is no
+  longer exported.
+* We build on the low-level ``mcp.server.lowlevel.Server`` rather than
+  ``MCPServer`` deliberately. ``MCPServer`` derives each tool's argument model
+  from the handler's Python signature and validates against it before the
+  handler runs. That has two consequences SourceLock cannot accept: unknown
+  arguments are silently dropped -- so a parameter like ``ssn`` never reaches
+  the guard and the call succeeds as though it had been filtered -- and its
+  validation errors echo the raw input value back to the client, which is the
+  one thing the guard exists to prevent. The low-level server hands us the
+  arguments untouched, so the guard sees exactly what the client sent.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import anyio
+import mcp.types as types
+from mcp.server.lowlevel import Server
+from mcp.server.models import InitializationOptions
+from mcp.server.stdio import stdio_server
+
+from . import __version__
+from .adapters import AdapterError, discovery_errors, find_tool, iter_tools
+from .guard import (
+    ParamsRejected,
+    PHIRejected,
+    safe_tool_name,
+    safe_validation_message,
+)
+from .http import SourceUnreachable
+
+__all__ = ["build_server", "call_tool_payload", "list_tool_names", "serve_stdio", "list_mcp_tools"]
+
+SERVER_NAME = "sourcelock"
+INSTRUCTIONS = (
+    "SourceLock serves public healthcare data sources with an evidence receipt on every "
+    "answer. Parameters are public and typed; input shaped like a patient record is refused "
+    "on a structural best-effort basis -- that is a guard, not a compliance control, so do "
+    "not send patient data to these tools on the strength of it. Each "
+    "result carries a receipt naming the source release, the SHA-256 of the raw bytes behind "
+    "the answer, and explicit non-claims stating what the answer does not prove. Read the "
+    "non_claims before acting on a result."
+)
+
+
+def call_tool_payload(name: str, arguments: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Invoke a tool by name and return a JSON-serialisable payload.
+
+    Raises ``KeyError`` for an unknown tool and
+    :class:`hc_source.guard.PHIRejected` for patient-shaped arguments.
+    """
+    tool = find_tool(name)
+    result = tool.invoke(arguments or {})
+    return {"data": result.data, "receipt": result.receipt.model_dump(mode="json")}
+
+
+def list_tool_names() -> list[str]:
+    return [t.name for t in iter_tools()]
+
+
+def list_mcp_tools() -> list[types.Tool]:
+    """Advertise each adapter's own parameter schema, unknown-fields-forbidden."""
+    return [
+        types.Tool(
+            name=spec.name,
+            description=spec.description,
+            inputSchema=spec.params_schema(),
+        )
+        for spec in iter_tools()
+    ]
+
+
+def _text_result(payload: str, *, is_error: bool = False) -> types.CallToolResult:
+    return types.CallToolResult(
+        content=[types.TextContent(type="text", text=payload)], isError=is_error
+    )
+
+
+async def _on_list_tools(ctx: Any, params: Any) -> types.ListToolsResult:
+    return types.ListToolsResult(tools=list_mcp_tools())
+
+
+async def _on_call_tool(ctx: Any, params: types.CallToolRequestParams) -> types.CallToolResult:
+    """Run a tool. Arguments arrive exactly as the client sent them."""
+    arguments = dict(params.arguments or {})
+
+    try:
+        payload = await anyio.to_thread.run_sync(
+            lambda: call_tool_payload(params.name, arguments)
+        )
+    except KeyError:
+        # The name is client-supplied text. Reflecting it back verbatim let a
+        # client write an arbitrary string into the server's error output --
+        # including one it had just been refused for sending as a parameter.
+        return _text_result(
+            f"No tool named {safe_tool_name(params.name)}. Call tools/list to see what "
+            "this server offers.",
+            is_error=True,
+        )
+    except SourceUnreachable as exc:
+        # Not the client's fault and not retryable by fixing the arguments.
+        # Carries a URL and a transport reason only -- no body, no parameters.
+        return _text_result(
+            f"{safe_tool_name(params.name)}: source unreachable -- {exc.url} ({exc.reason}"
+            + (f", HTTP {exc.status}" if exc.status else "")
+            + "). No answer was returned because there would be no evidence behind it.",
+            is_error=True,
+        )
+    except (PHIRejected, ParamsRejected) as exc:
+        # Both carry field names and rule text, never values, by construction.
+        return _text_result(str(exc), is_error=True)
+    except ValueError as exc:
+        # Defence in depth: ToolSpec.invoke converts pydantic's ValidationError
+        # into ParamsRejected, so a bare ValueError here came from adapter code.
+        # Report the field and the rule, never the value: a rejected value may
+        # be exactly what must not be echoed.
+        return _text_result(
+            f"{safe_tool_name(params.name)}: invalid parameters. {_safe_reason(exc)}",
+            is_error=True,
+        )
+
+    text = json.dumps(payload, indent=2)
+    return types.CallToolResult(
+        content=[types.TextContent(type="text", text=text)],
+        structuredContent=payload,
+        isError=False,
+    )
+
+
+def _safe_reason(exc: ValueError) -> str:
+    """Summarise a validation failure without repeating any input value.
+
+    Round-1 finding C1: the previous version read ``error["msg"]`` directly and
+    correctly avoided ``error["input"]`` -- but pydantic copies a custom
+    validator's text into ``msg`` verbatim, so a validator that quoted its input
+    put the value straight back into the client's error. ``safe_validation_message``
+    scrubs ``msg`` against ``input`` before it is used.
+    """
+    errors = getattr(exc, "errors", None)
+    if not callable(errors):
+        return type(exc).__name__
+    return safe_validation_message(exc)
+
+
+def build_server() -> Server:
+    """A low-level MCP Server with SourceLock's tool handlers wired in."""
+    return Server(
+        name=SERVER_NAME,
+        version=__version__,
+        instructions=INSTRUCTIONS,
+        on_list_tools=_on_list_tools,
+        on_call_tool=_on_call_tool,
+    )
+
+
+def serve_stdio() -> None:
+    """Run the server over stdio. Blocks until the client disconnects.
+
+    Refuses to start if any adapter module failed to import. Everywhere else a
+    load failure can be printed and read by a human; here the consumer is an
+    agent that sees only ``tools/list``, where a broken adapter and an
+    uninstalled one are indistinguishable. An agent that cannot see the gap will
+    answer around it, which is the worst outcome this product has: a confident
+    answer with a source silently missing from it.
+    """
+    errors = discovery_errors()
+    if errors:
+        raise AdapterError(
+            "refusing to serve MCP: "
+            + "; ".join(str(e) for e in errors)
+            + ". An MCP client cannot see a load failure -- it sees a shorter tools/list "
+            "and assumes that is the whole product. Fix the adapter, or remove its module "
+            "deliberately, before serving."
+        )
+    server = build_server()
+
+    async def _run() -> None:
+        async with stdio_server() as (read_stream, write_stream):
+            await server.run(
+                read_stream,
+                write_stream,
+                InitializationOptions(
+                    server_name=SERVER_NAME,
+                    server_version=__version__,
+                    capabilities=server.get_capabilities(),
+                    instructions=INSTRUCTIONS,
+                ),
+            )
+
+    anyio.run(_run)

hc_source/npi.py

@@ -0,0 +1,50 @@
+"""The one NPI validator.
+
+The National Provider Identifier is a 10-digit number whose last digit is a Luhn
+check digit computed over the number prefixed with the NPI issuer prefix
+``80840``. Because that prefix is constant, its Luhn contribution is the constant
+``24``, which is why the loop below starts there.
+
+This lives in ``hc_source/`` rather than in an adapter because two adapters need
+it and a second copy is a second chance to be wrong: ``provider`` rejected
+mistyped NPIs at the parameter boundary while ``leie`` accepted any ten digits,
+so a transposed NPI produced a confident "not excluded" screen against a number
+that cannot exist.
+"""
+
+from __future__ import annotations
+
+__all__ = ["NPI_PATTERN", "npi_check_digit_ok", "validate_npi"]
+
+#: Shape only. Shape is not validity -- always follow it with the check digit.
+NPI_PATTERN = r"^\d{10}$"
+
+#: Luhn contribution of the constant ``80840`` issuer prefix.
+_PREFIX_CONTRIBUTION = 24
+
+
+def npi_check_digit_ok(npi: str) -> bool:
+    """True when ``npi`` is ten digits whose check digit passes the 80840 Luhn."""
+    if len(npi) != 10 or not npi.isdigit():
+        return False
+    digits = [int(c) for c in npi]
+    total = _PREFIX_CONTRIBUTION
+    for i, d in enumerate(digits[:9]):
+        if i % 2 == 0:  # doubling starts from the rightmost base digit (index 8)
+            d *= 2
+            if d > 9:
+                d -= 9
+        total += d
+    return (10 - total % 10) % 10 == digits[9]
+
+
+def validate_npi(npi: str) -> str:
+    """Return ``npi`` unchanged, or raise ``ValueError`` naming the rule it broke.
+
+    Suitable as the body of a pydantic ``field_validator``. The message never
+    repeats the value: a rejected NPI is caller-supplied input, and echoing it
+    back is how a value we refused ends up in a log.
+    """
+    if not npi_check_digit_ok(npi):
+        raise ValueError("not a valid NPI: check digit fails the 80840 Luhn test")
+    return npi