pmcp 2.7.2__tar.gz → 2.7.3__tar.gz

pmcp-2.7.3/.consiliency/plans/detailed-auth-trust-split-20260830-1600.md

@@ -0,0 +1,199 @@
+# Detailed plan: stop vouching for URLs a downstream server supplied
+
+> **Revision 3 (2026-08-30).** Rev 2 boarded 1 DISAGREE / 1 PARTIALLY AGREE /
+> 1 AGREE. Its `fetch_json_metadata` criterion was **already satisfied by
+> unchanged `main`**, it proposed deleting a **frozen interface**, and it left
+> the string agents actually follow unqualified. All three verified.
+>
+> **Revision 2 (2026-08-30).** Boarded 2 DISAGREE. Rev 1 named the wrong types
+> and would have broken a frozen operator contract. Both verified below.
+
+## Task
+
+Close Consiliency/pmcp#211. `sanitize_public_auth_url` applies one permissiveness
+to inputs of very different provenance, and pmcp presents the result as
+validated. A downstream server can hand back a URL on an internal host and have
+pmcp show it to the operator as though pmcp checked it.
+
+## What #210 already closed — measured today, post-merge
+
+#211 was filed before #210 landed. Re-checking the untrusted elicitation path
+now:
+
+```
+https://0xA9FEA9FE/x              rejected     <- #210 closed this
+https://metadata.google.internal/x  ACCEPTED   <- remains
+http://127.0.0.1/cb                 ACCEPTED   <- remains
+https://auth.vendor.com/x           ACCEPTED   <- legitimate, must stay
+```
+
+So the numeric-form relay is gone. **What is left is names, and loopback HTTP.**
+That is a materially smaller issue than filed, and the plan is scoped to it.
+
+Two other open questions from the issue, now answered:
+
+- **The JWKS URL is purely operator-supplied.** It reaches
+  `transport/http.py:281` only from `cli.py:2295`'s `--oauth-jwks-url`. It does
+  **not** arrive from a manifest or registry entry. The issue speculated it
+  might; it does not.
+- **`fetch_json_metadata` still has no production caller** — only its own
+  definition at `auth.py:756`.
+
+## The shape of the fix
+
+**Do not reject names on the untrusted paths.** A board round established that
+rejecting unverifiable names there would refuse
+`https://auth.vendor.com/...` from a well-behaved server — killing the feature
+the check exists to protect. Rejecting is right for a *fetch* and wrong for a
+*relay*.
+
+The harm is not that pmcp accepts the URL. It is that pmcp **presents it as
+validated**. So:
+
+- **Fail closed on fetches.** Anything pmcp will retrieve must be verifiably
+  public.
+- **Stop vouching on relays.** Keep passing the URL through, but stop implying
+  pmcp checked where it points.
+
+### `src/pmcp/auth.py` (modify)
+
+- `fetch_json_metadata` (`:756`) — **gate it. Do not delete it.**
+  **WAS WRONG (rev 2):** it said deleting is preferred. Verified — this function
+  is a **frozen interface**: `plans/phase-plan-v4-safeurl.md:48` lists it under
+  *Interfaces provided*, and **IF-0-SAFEURL-4** names it by contract. Deleting it
+  breaks that freeze; gating preserves compatibility.
+
+  It fetches, so it is the fail-closed side: it must reject anything that is not
+  a **verifiably public literal** — names included, and loopback HTTP included.
+  Verified on `main` today: `https://10.0.0.1/x` is already rejected, but
+  `http://127.0.0.1/x` and `https://metadata.google.internal/x` both **reach
+  `urlopen`**.
+- `sanitize_url_elicitation_url` (`:485`) — modify — **split it by provenance.**
+  **WAS WRONG (rev 1):** it said "stop passing `allow_loopback_http=True`",
+  full stop. Verified: this helper is **shared** between the downstream-payload
+  path (`auth.py:736`) and the **operator-supplied** acknowledgement path
+  (`handlers.py:4592`, `parsed.elicitation_url`). Removing loopback globally
+  would break the operator's local-OAuth flow, which `plans/phase-plan-v4-elicit.md`
+  records as a frozen contract. The remote path must lose loopback HTTP; the
+  operator path must keep it. Two policies, two call sites, regression tests for
+  both.
+- A `verified` signal on the returned value — add — whether the host was
+  verified as a public literal or merely accepted as an unresolved name. It must
+  **default to unverified**: a default of "verified" reintroduces vouching at any
+  call site the change misses.
+
+### Presentation (modify)
+
+- **`UrlElicitationInfo` (`types.py:163`) is the primary relay surface and rev 1
+  omitted it entirely.** Its docstring reads *"URL-mode elicitation details **safe
+  to display to users**"* — the type asserts precisely the claim this issue
+  disproves. It carries `url`, `message`, `next_step` and no verification field,
+  and `handlers.py:4610` constructs it with an unconditional open-the-URL
+  instruction. Add the signal here first; without it AC 3 cannot be met on the
+  surface that actually reaches an operator. Correct the docstring too.
+- `cli.py` — where `url_elicitations` are shown — must state that an unverified
+  URL's destination was not checked, in **both** the human text and `--json`.
+  Note the copy must not say "came from the server" on the acknowledge path
+  (`cli.py:2603-2605`), which echoes an **operator-supplied** URL.
+- `cli_commands/doctor.py:90-95` reports sanitize success as
+  `[OK] … configured at {url}` for a name — operator config rather than a
+  downstream payload, but another vouch. Qualify it or state why it is exempt.
+- **`AuthMetadataInfo` needs a PER-URL signal, not one object-level bool.** It
+  carries five independent URL fields; a single flag cannot be honest when one is
+  a public literal and another is a name. Rev 1 specified one signal per object.
+  **Keep the URL fields `str | None`** — `transport/http.py:373` interpolates
+  `protected_resource_metadata_url` straight into a `WWW-Authenticate` header, so
+  wrapping them is a silent contract break. Use companion flags or a side map.
+- **Keep `sanitize_url_elicitation_url` returning `str`** (frozen as
+  IF-0-ELICIT-1). Carry `verified` on a small result object or a parallel
+  predicate, so every string-equality test does not have to move.
+- `AuthChallengeInfo.resource_metadata_url` — same per-URL treatment.
+
+## Documentation impact
+
+- `CHANGELOG.md` — `### Changed`: pmcp no longer implies it verified where a
+  server-supplied auth URL points, and no longer accepts a loopback HTTP URL from
+  a downstream server.
+- `README.md` / `SECURITY.md` — the #210 wording already says the check filters
+  IP literals. Extend to state that a server-supplied URL is relayed unverified
+  and is presented as such.
+
+## Dependencies & order
+
+1. The `verified` signal on `UrlElicitationInfo` first, defaulting to
+   unverified, with unit tests — it is the surface that reaches an operator.
+2. The provenance split on `sanitize_url_elicitation_url` — remote loses
+   loopback HTTP, operator keeps it — with regression tests both ways.
+3. `fetch_json_metadata` — delete or gate.
+4. Presentation changes.
+5. Docs.
+
+## Verification
+
+```bash
+uv run pytest -q tests/test_auth.py
+uv run pytest -q
+uv run ruff check src/ tests/ && uv run ruff format --check src/ tests/ && uv run mypy src/
+```
+
+`/tmp/package.json` and `/tmp/node_modules` on this host make ~107 npm-identity
+tests fail locally in a way that reproduces on a clean `main` export
+(`tests/conftest.py`). Verify against `main` before blaming this diff.
+
+## Acceptance criteria
+
+- [ ] A **downstream** elicitation payload carrying `http://127.0.0.1/cb` is
+      **rejected**, proven by a test failing against `main`. **And the operator
+      path at `handlers.py:4592` still accepts it** — both directions, or the
+      change breaks a frozen contract. `test_sanitize_url_elicitation_url_allows_loopback_http`
+      inverts for the remote path only.
+- [ ] `https://auth.vendor.com/...` from a downstream server is **still
+      accepted** — the feature must survive. A change that rejects names must not
+      pass.
+- [ ] A relayed URL whose host is an unresolved name is marked **unverified** on
+      `UrlElicitationInfo`, and the gateway output, the CLI human text **and**
+      `--json` all say so. Asserted on emitted text, not on a field's presence.
+      Rev 1's criteria exercised only elicitation and CLI, which would let the
+      challenge and metadata surfaces stay misleading while every test passed.
+- [ ] `AuthMetadataInfo` with a **mix** — one public literal, one name — reports
+      them differently. A single object-level flag cannot pass this.
+- [ ] **`AuthChallengeInfo.resource_metadata_url`** is covered by the same four
+      assertions: unresolved name marked unverified, public literal not marked,
+      default unverified, and the serialized output carries it. Rev 2 required
+      per-URL treatment for this surface in *Changes* but wrote **no criterion**
+      for it — so leaving `parse_www_authenticate` untouched would have satisfied
+      every listed criterion while it still relays
+      `https://metadata.google.internal/meta` unmarked.
+- [ ] **The `next_step` text is qualified.** The open-the-URL instruction is
+      copied to `handlers.py:2133`, `:2786`, `:4215`, `:4349`, `:4436` and printed
+      by `cli.py:2519-2521`. That string is what an agent follows. A JSON
+      `verified: false` plus a CLI sidebar, with `next_step` still saying "open
+      the URL" unqualified, must **not** pass.
+- [ ] The signal defaults to **unverified** — proven by constructing the type
+      without it and asserting the unverified presentation.
+- [ ] A relayed URL whose host is a verified public literal is **not** marked
+      unverified — so the signal distinguishes, rather than labelling everything.
+- [ ] `fetch_json_metadata` rejects **`http://127.0.0.1/x`** and **an unresolved
+      hostname**, each **without invoking the opener** — asserted by patching the
+      opener and proving it was never called.
+      **WAS WRONG (rev 2):** the criterion was "rejects a non-public literal",
+      which unchanged `main` **already satisfies** for `https://10.0.0.1/x`. It
+      could be passed by doing nothing, while the two forms that actually reach
+      `urlopen` stayed open. This is the fourth vacuous criterion in this
+      project; it was caught because a seat ran it rather than read it.
+- [ ] Full suite green.
+
+## Non-goals
+
+- **Resolving hostnames.** Rejected across three board rounds: TOCTOU, a lookup
+  on caller-supplied input, and it is not SSRF defence without connection-time IP
+  pinning.
+- **The trailing-dot IPv4 form** (`169.254.169.254.`), which takes the name path.
+  It is name-shaped; if the `verified` signal is right, it is relayed unverified
+  like any other name.
+- Re-opening #210's literal classification. It is closed and pinned by 22 tests.
+
+## Execution Policy
+
+- execute: effort=medium, reason=small diff, but it changes what pmcp claims to
+  an operator, and the risk is over-rejecting a legitimate auth flow

{pmcp-2.7.2 → pmcp-2.7.3}/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.7.3] - 2026-08-31
+
+### Changed
+- **PMCP no longer implies it verified where a server-supplied auth URL
+  points.** It never did: `_is_public_auth_host` classifies IP literals and
+  accepts a DNS name **without resolving it**, so
+  `https://metadata.google.internal/...` in an elicitation payload or a
+  `WWW-Authenticate` header was relayed to the operator — and to an agent —
+  looking like something PMCP had checked. Names are still relayed, because
+  refusing unresolvable ones would refuse a well-behaved server's
+  `https://auth.vendor.com/...` too; what changed is what PMCP claims about
+  them. `UrlElicitationInfo.url_verified`, `AuthMetadataInfo.verified_urls`
+  (per URL field, since those five URLs are independent) and
+  `AuthChallengeInfo.resource_metadata_url_verified` report whether PMCP itself
+  classified the host as a public literal, and all three default to
+  **unverified**. The qualification is threaded into the `next_step` string an
+  agent actually follows, and into `pmcp auth connect` / `pmcp auth acknowledge`
+  output in both human text and `--json`. `pmcp doctor` no longer reports a bare
+  `[OK] ... configured at <name>` for a host it did not verify
+  ([#211](https://github.com/Consiliency/pmcp/issues/211)).
+- **A downstream server can no longer hand back a loopback `http://` URL.**
+  `sanitize_url_elicitation_url` now splits by provenance: a URL parsed out of a
+  server's error payload loses loopback HTTP, while one the operator types into
+  `gateway.auth_connect` keeps it, because local OAuth redirects to
+  `http://127.0.0.1`. The default is the strict remote policy, so a call site
+  missed by a future change fails closed (#211).
+- **`fetch_json_metadata` now fails closed.** PMCP retrieves that URL itself, so
+  "accepted but unresolved" is not good enough there: the host must be one PMCP
+  verified as a public IP literal, and a refused URL is rejected before the
+  opener is reached rather than fetched and judged afterwards. `http://127.0.0.1/x`
+  and unresolved names previously both reached `urlopen` (#211).
+
 ## [2.7.2] - 2026-08-30
 
 ### Fixed

{pmcp-2.7.2 → pmcp-2.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pmcp
-Version: 2.7.2
+Version: 2.7.3
 Summary: PMCP - Progressive MCP: Minimal context bloat with on-demand tool discovery
 Project-URL: Repository, https://github.com/Consiliency/pmcp
 Project-URL: Homepage, https://github.com/Consiliency/pmcp
@@ -240,7 +240,13 @@ literals** — private, CGNAT, link-local, loopback, multicast, site-local, and
 unspecified — including IPv4 addresses embedded in IPv6 literals and legacy
 numeric forms such as `2852039166`. This is a filter on literals only: a DNS
 name is accepted **without being resolved**, so a name that points at an
-internal address still passes
+internal address still passes. PMCP therefore no longer presents such a URL as
+one it checked: a server-supplied URL is **relayed unverified and presented as
+such** — `UrlElicitationInfo.url_verified`, `AuthMetadataInfo.verified_urls`,
+and `AuthChallengeInfo.resource_metadata_url_verified` all default to
+unverified, and the caveat is carried in the `next_step` an agent follows and in
+CLI output. Where PMCP *fetches* a URL itself it fails closed instead, requiring
+a verified public literal
 ([#211](https://github.com/Consiliency/pmcp/issues/211)). PMCP is still not an
 Authorization Server and does not provide dynamic client registration, SSO,
 RBAC, billing, or a complete multi-tenant identity service.

{pmcp-2.7.2 → pmcp-2.7.3}/README.md

@@ -176,7 +176,13 @@ literals** — private, CGNAT, link-local, loopback, multicast, site-local, and
 unspecified — including IPv4 addresses embedded in IPv6 literals and legacy
 numeric forms such as `2852039166`. This is a filter on literals only: a DNS
 name is accepted **without being resolved**, so a name that points at an
-internal address still passes
+internal address still passes. PMCP therefore no longer presents such a URL as
+one it checked: a server-supplied URL is **relayed unverified and presented as
+such** — `UrlElicitationInfo.url_verified`, `AuthMetadataInfo.verified_urls`,
+and `AuthChallengeInfo.resource_metadata_url_verified` all default to
+unverified, and the caveat is carried in the `next_step` an agent follows and in
+CLI output. Where PMCP *fetches* a URL itself it fails closed instead, requiring
+a verified public literal
 ([#211](https://github.com/Consiliency/pmcp/issues/211)). PMCP is still not an
 Authorization Server and does not provide dynamic client registration, SSO,
 RBAC, billing, or a complete multi-tenant identity service.

{pmcp-2.7.2 → pmcp-2.7.3}/SECURITY.md

@@ -72,8 +72,17 @@ PMCP is a local-first MCP gateway. Its default security posture assumes:
   RFC 6052 NAT64, RFC 3056 6to4, RFC 4380 Teredo, RFC 5214 ISATAP) and legacy
   numeric forms such as `2852039166` or `0177.0.0.1`. **A DNS name is accepted
   without being resolved**, so a name pointing at an internal address is not
-  caught. Tracked in
-  [#211](https://github.com/Consiliency/pmcp/issues/211).
+  caught. PMCP does not resolve names deliberately: a lookup is
+  TOCTOU-vulnerable and is not SSRF defence without connection-time IP pinning.
+  What it does instead is stop claiming otherwise — **a server-supplied URL is
+  relayed unverified and presented as such**, via
+  `UrlElicitationInfo.url_verified`, `AuthMetadataInfo.verified_urls` (one entry
+  per URL field), and `AuthChallengeInfo.resource_metadata_url_verified`, all
+  defaulting to unverified, with the caveat carried in the `next_step` string an
+  agent follows and in `pmcp auth` output. Paths where PMCP fetches the URL
+  itself fail closed and require a verified public literal, and a URL from a
+  downstream server's payload may not be loopback `http://`
+  ([#211](https://github.com/Consiliency/pmcp/issues/211)).
 - **No mTLS**: clients are not authenticated by certificate; only Bearer token.
 - **No per-tool ACL on HTTP**: any valid token can invoke any tool. Tool-level policy is
   enforced at the MCP layer, not the HTTP layer.

{pmcp-2.7.2 → pmcp-2.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pmcp"
-version = "2.7.2"
+version = "2.7.3"
 description = "PMCP - Progressive MCP: Minimal context bloat with on-demand tool discovery"
 readme = "README.md"
 license = "MIT"

{pmcp-2.7.2 → pmcp-2.7.3}/src/pmcp/__init__.py

@@ -1,3 +1,3 @@
 """PMCP - A meta-server for minimal Claude Code tool bloat."""
 
-__version__ = "2.7.2"
+__version__ = "2.7.3"

{pmcp-2.7.2 → pmcp-2.7.3}/src/pmcp/auth.py

@@ -10,7 +10,7 @@ from collections.abc import Mapping
 from dataclasses import dataclass
 from ipaddress import IPv4Address, IPv6Address, ip_address, ip_network
 from itertools import product
-from typing import Any
+from typing import Any, Literal
 from urllib.error import HTTPError
 from urllib.parse import parse_qsl, quote, urlparse, urlunparse
 from urllib.request import HTTPRedirectHandler, Request, build_opener
@@ -260,6 +260,66 @@ def _is_public_auth_host(hostname: str) -> bool:
     return True
 
 
+def _is_verified_public_auth_host(hostname: str) -> bool:
+    """Report whether PMCP itself classified this host as a public literal.
+
+    This is the honest half of :func:`_is_public_auth_host`. That function
+    returns True for a DNS name, because rejecting unresolvable names would
+    refuse every legitimate ``auth.vendor.com``. But "not rejected" is not
+    "checked", and presenting the two identically is the vouch #211 reports.
+
+    A name therefore returns **False** here: PMCP does not resolve names -- a
+    deliberate non-goal, since a lookup is TOCTOU-vulnerable and is not SSRF
+    defence without connection-time IP pinning -- so it does not know where one
+    points and must not imply that it does.
+    """
+    if hostname.lower() == "localhost":
+        return False
+    address: IPv4Address | IPv6Address | None
+    try:
+        address = ip_address(hostname)
+    except ValueError:
+        address = None
+    if address is not None:
+        return _is_public_ip(address)
+    numeric = _legacy_numeric_addresses(hostname)
+    if numeric:
+        return all(_is_public_ip(candidate) for candidate in numeric)
+    return False
+
+
+def is_verified_public_auth_url(url: str) -> bool:
+    """Report whether PMCP verified where an auth URL points.
+
+    True only for an absolute ``https://`` URL whose host PMCP classified as a
+    public IP literal. False for every DNS name, every non-public literal, and
+    every ``http://`` URL -- a cleartext hop's destination is not authenticated
+    even when the address is public.
+
+    Callers use this to decide what to *claim*, not what to accept: a relay path
+    keeps passing an unverified URL through, it just stops vouching for it.
+    """
+    try:
+        parsed = urlparse(url)
+        hostname = parsed.hostname
+        _ = parsed.port
+    except ValueError:
+        return False
+    if parsed.scheme != "https" or not parsed.netloc or not hostname:
+        return False
+    return _is_verified_public_auth_host(hostname)
+
+
+# One provenance-neutral sentence, used on both the downstream relay path and
+# the operator acknowledgement path. The acknowledge path echoes a URL the
+# operator typed, so the copy must not attribute it to "the server".
+UNVERIFIED_URL_CAVEAT = (
+    "PMCP has not verified where this URL points -- it checks the URL's form "
+    "and rejects private address literals, but it does not resolve host names. "
+    "Confirm the destination yourself before opening it."
+)
+
+
 def sanitize_public_auth_url(url: str, *, allow_loopback_http: bool = False) -> str:
     """Validate and redact a public absolute auth metadata or elicitation URL."""
     try:
@@ -482,10 +542,33 @@ def validate_resource_server_token(
     )
 
 
-def sanitize_url_elicitation_url(url: str) -> str:
-    """Validate and redact a URL-mode elicitation URL."""
+def sanitize_url_elicitation_url(
+    url: str, *, provenance: Literal["remote", "operator"] = "remote"
+) -> str:
+    """Validate and redact a URL-mode elicitation URL.
+
+    This helper is shared by two call sites whose inputs have very different
+    provenance, and one permissiveness cannot be right for both (#211):
+
+    ``remote`` (the default)
+        The URL came out of a downstream server's error payload. A loopback
+        ``http://`` URL from there is an attempt to steer the operator at
+        something on the operator's own machine, so it is refused.
+
+    ``operator``
+        The URL was typed by the operator into ``gateway.auth_connect``. Local
+        OAuth redirects back to ``http://127.0.0.1``, and refusing that would
+        break the frozen local-consent flow, so loopback HTTP stays allowed.
+
+    The default is the strict side deliberately: a call site this change misses
+    should lose loopback, not silently keep it. Returns ``str`` -- the frozen
+    IF-0-ELICIT-1 shape. Ask :func:`is_verified_public_auth_url` separately for
+    whether PMCP actually verified the destination.
+    """
     try:
-        return sanitize_public_auth_url(url, allow_loopback_http=True)
+        return sanitize_public_auth_url(
+            url, allow_loopback_http=provenance == "operator"
+        )
     except ValueError as exc:
         raise ValueError("Invalid URL-mode elicitation URL.") from exc
 
@@ -585,6 +668,7 @@ def parse_www_authenticate(header: str) -> AuthChallengeInfo | None:
     missing = params.get("missing_scope") or scope or ""
     missing_scopes = [part for part in missing.split() if part]
     resource_metadata_url = None
+    resource_metadata_url_verified = False
     if params.get("resource_metadata"):
         try:
             resource_metadata_url = sanitize_public_auth_url(
@@ -592,10 +676,15 @@ def parse_www_authenticate(header: str) -> AuthChallengeInfo | None:
             )
         except ValueError:
             resource_metadata_url = None
+        else:
+            resource_metadata_url_verified = is_verified_public_auth_url(
+                params["resource_metadata"]
+            )
 
     return AuthChallengeInfo(
         scheme=scheme,
         resource_metadata_url=resource_metadata_url,
+        resource_metadata_url_verified=resource_metadata_url_verified,
         scope=scope,
         missing_scopes=missing_scopes,
         error=params.get("error"),
@@ -633,18 +722,29 @@ def normalize_auth_metadata(
 ) -> AuthMetadataInfo:
     """Normalize untrusted authorization metadata into PMCP's public shape."""
     normalized_diagnostics = [sanitize_auth_diagnostic(d) for d in (diagnostics or [])]
+    # Per-field, not per-object: these five URLs are independent, so one flag
+    # cannot be honest about a mix of a literal and a name (#211).
+    verified_urls: list[str] = []
 
     def public_url(raw_url: str | None, field_name: str) -> str | None:
         if not raw_url:
             return None
         try:
-            return sanitize_public_auth_url(raw_url)
+            safe_url = sanitize_public_auth_url(raw_url)
         except ValueError as exc:
             normalized_diagnostics.append(
                 f"{field_name} ignored: {sanitize_auth_diagnostic(exc)} "
                 f"({redact_auth_url(raw_url)})"
             )
             return None
+        if is_verified_public_auth_url(raw_url):
+            verified_urls.append(field_name)
+        else:
+            normalized_diagnostics.append(
+                f"{field_name} is relayed unverified: PMCP did not resolve "
+                f"{safe_url} and cannot confirm where it points."
+            )
+        return safe_url
 
     metadata = metadata or {}
     scopes_supported = metadata.get("scopes_supported")
@@ -691,6 +791,7 @@ def normalize_auth_metadata(
         granted_scopes=granted_scopes or [],
         missing_scopes=missing_scopes or [],
         diagnostics=normalized_diagnostics,
+        verified_urls=verified_urls,
     )
 
 
@@ -733,20 +834,30 @@ def parse_url_elicitation_error(payload: object) -> list[UrlElicitationInfo]:
         if not isinstance(elicitation_id, str) or not isinstance(url, str):
             continue
         try:
-            safe_url = sanitize_url_elicitation_url(url)
+            safe_url = sanitize_url_elicitation_url(url, provenance="remote")
         except ValueError:
             continue
         message = entry.get("message")
+        verified = is_verified_public_auth_url(url)
+        # `next_step` is the string an agent actually follows, so the caveat has
+        # to live inside it. A `url_verified: false` field alongside an
+        # unqualified "Open the URL" instruction still gets the URL opened.
+        follow_up = (
+            "open the URL out of band, complete consent, then call "
+            f"gateway.auth_connect(auth_mode='url_elicitation', "
+            f"server_name='<server>', elicitation_id='{elicitation_id}', "
+            "consent_acknowledged=true)."
+        )
         parsed_entries.append(
             UrlElicitationInfo(
                 elicitation_id=elicitation_id,
                 url=safe_url,
+                url_verified=verified,
                 message=message if isinstance(message, str) else None,
                 next_step=(
-                    "Open the URL out of band, complete consent, then call "
-                    f"gateway.auth_connect(auth_mode='url_elicitation', "
-                    f"server_name='<server>', elicitation_id='{elicitation_id}', "
-                    "consent_acknowledged=true)."
+                    f"{follow_up[0].upper()}{follow_up[1:]}"
+                    if verified
+                    else f"{UNVERIFIED_URL_CAVEAT} Once confirmed, {follow_up}"
                 ),
             )
         )
@@ -756,11 +867,28 @@ def parse_url_elicitation_error(payload: object) -> list[UrlElicitationInfo]:
 def fetch_json_metadata(
     url: str, *, timeout: float = 5.0
 ) -> tuple[dict[str, object] | None, str | None]:
-    """Fetch public auth metadata without forwarding credentials."""
+    """Fetch public auth metadata without forwarding credentials.
+
+    This is the fail-closed side of #211. PMCP *retrieves* this URL itself, so
+    "accepted but unverified" is not good enough here the way it is on a relay
+    path: the host must be one PMCP classified as a public IP literal. Loopback
+    HTTP and unresolved names are both refused, and refused **before** the
+    opener is reached, so a rejected URL is never requested.
+
+    This gates the interface rather than removing it: ``fetch_json_metadata`` is
+    frozen by IF-0-SAFEURL-4 (``plans/phase-plan-v4-safeurl.md``), so deleting
+    it would break that freeze even though it has no production caller today.
+    """
     try:
-        safe_url = sanitize_public_auth_url(url, allow_loopback_http=True)
+        safe_url = sanitize_public_auth_url(url)
     except ValueError as exc:
         return None, sanitize_auth_diagnostic(exc)
+    if not is_verified_public_auth_url(url):
+        return None, (
+            f"{safe_url}: refused before fetching -- PMCP retrieves only URLs "
+            "whose host it verified as a public IP literal, and it does not "
+            "resolve host names."
+        )
     try:
         request = Request(safe_url, headers={"Accept": "application/json"})
         with urlopen(request, timeout=timeout) as response:

{pmcp-2.7.2 → pmcp-2.7.3}/src/pmcp/cli.py

@@ -962,6 +962,20 @@ def _sanitize_cli_payload(value: Any) -> Any:
     return value
 
 
+def _url_verification_suffix(elicitation: dict[str, Any]) -> str:
+    """Qualify a displayed elicitation URL that PMCP did not verify.
+
+    Deliberately provenance-neutral: this is printed both for a URL relayed by a
+    downstream server and, on the acknowledge path, for one the operator typed,
+    so it must not claim the URL "came from the server". Absent or false
+    ``url_verified`` both mean unverified -- an older gateway that does not send
+    the field must not be read as a clean bill of health (#211).
+    """
+    if elicitation.get("url_verified") is True:
+        return ""
+    return " (destination not verified by pmcp)"
+
+
 def _format_auth_evidence(
     payload: dict[str, Any],
     *,
@@ -997,6 +1011,11 @@ def _format_auth_evidence(
         ]
         if ids:
             parts.append("elicitations=" + ",".join(ids))
+        if any(
+            isinstance(item, dict) and item.get("url_verified") is not True
+            for item in url_elicitations
+        ):
+            parts.append("url_destination=unverified")
 
     next_step = payload.get("next_step")
     if not next_step and semantics:
@@ -2513,7 +2532,10 @@ async def run_auth_connect(args: argparse.Namespace) -> None:
             else:
                 print(first.get("message", "URL-mode elicitation required."))
                 if elicitation.get("url"):
-                    print(f"URL: {_redact_url_credentials(str(elicitation['url']))}")
+                    print(
+                        f"URL: {_redact_url_credentials(str(elicitation['url']))}"
+                        + _url_verification_suffix(elicitation)
+                    )
                 if elicitation.get("elicitation_id"):
                     print(f"Elicitation ID: {elicitation['elicitation_id']}")
                 next_step = elicitation.get("next_step") or first.get("next_step")
@@ -2602,7 +2624,10 @@ async def run_auth_acknowledge(args: argparse.Namespace) -> None:
             print(auth_result.get("message", "URL-mode elicitation acknowledged."))
             url_elicitation = auth_result.get("url_elicitation")
             if isinstance(url_elicitation, dict) and url_elicitation.get("url"):
-                print(f"URL: {_redact_url_credentials(str(url_elicitation['url']))}")
+                print(
+                    f"URL: {_redact_url_credentials(str(url_elicitation['url']))}"
+                    + _url_verification_suffix(url_elicitation)
+                )
             if auth_result.get("next_step"):
                 print(f"Next step: {auth_result['next_step']}")
     finally:

{pmcp-2.7.2 → pmcp-2.7.3}/src/pmcp/cli_commands/doctor.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from urllib.parse import urlparse
 
 from pmcp.auth import (
+    is_verified_public_auth_url,
     redact_auth_url,
     sanitize_auth_diagnostic,
     sanitize_public_auth_url,
@@ -87,11 +88,21 @@ def collect_remote_header_diagnostics(
                     )
                 )
             else:
+                # `sanitize_public_auth_url` succeeding means the URL's form is
+                # valid and its host is not a private address literal -- not
+                # that pmcp knows where it points. Reporting a bare `[OK] ...
+                # configured at <name>` claimed the latter (#211).
+                qualifier = (
+                    ""
+                    if is_verified_public_auth_url(metadata_url)
+                    else " (host not verified; pmcp does not resolve names)"
+                )
                 checks.append(
                     (
                         "remote",
                         "ok",
-                        f"{server_name}: {metadata_key} configured at {safe_metadata_url}.",
+                        f"{server_name}: {metadata_key} configured at "
+                        f"{safe_metadata_url}{qualifier}.",
                     )
                 )