attestari-mcp 0.1.0__tar.gz

attestari_mcp-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+node_modules/
+.next/
+out/
+.vercel/
+.env
+.env.local
+.env.*.local
+*.tsbuildinfo
+next-env.d.ts
+.DS_Store
+
+# analysis pipeline
+analysis/.venv/
+analysis/api/.venv/
+analysis/api/.pytest_cache/
+analysis/api/.ruff_cache/
+analysis/evidence/
+analysis/**/__pycache__/
+analysis/.pytest_cache/
+analysis/runs/*/prompts.json
+analysis/.hypothesis/
+
+# infra: files rendered from templates by the scripts, applied and removed
+infra/.*.rendered.*
+
+analysis/corpus/.scratch/
+
+# accounts service
+accounts/.venv/
+accounts/.pytest_cache/
+accounts/.ruff_cache/
+accounts/**/__pycache__/
+
+# the MCP server (mcp/, docs/app.attestari.ai/phase-1-mcp-plan.md)
+mcp/.venv/
+mcp/.pytest_cache/
+mcp/.ruff_cache/
+mcp/dist/
+mcp/**/__pycache__/
+
+# web app: what the end-to-end tests leave behind
+webapp/e2e/.outbox/
+webapp/e2e/.results/
+webapp/e2e/.outbox-*/
+webapp/e2e/.results-*/
+.next-*/
+webapp/e2e/.report/

attestari_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Elite360 Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

attestari_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.5
+Name: attestari-mcp
+Version: 0.1.0
+Summary: Attestari's verdict on an npm or PyPI package version, over MCP: the lookup API's answer, asked before a package is installed.
+Project-URL: Homepage, https://attestari.ai
+Project-URL: Documentation, https://attestari.ai/pricing#line-2
+Author: Attestari
+License-Expression: MIT
+License-File: LICENSE
+Keywords: attestari,mcp,model-context-protocol,security,supply-chain
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.12
+Requires-Dist: httpx2>=2.13
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pydantic>=2.9
+Requires-Dist: starlette>=0.40
+Requires-Dist: uvicorn>=0.30
+Description-Content-Type: text/markdown
+
+# attestari-mcp
+
+<!-- mcp-name: ai.attestari/attestari -->
+
+Attestari's verdict on an npm or PyPI package version, over the Model Context Protocol. The answer is the Attestari
+lookup API's: the grade, the decision, the confirmed findings by reason code and place, and the methodology version
+and document hash the decision cites. "Not examined" is its own answer and is never a sign that a package is safe.
+
+Every lookup needs an Attestari API key (the Developer tier and above, https://attestari.ai/pricing#line-2) and is
+counted as one lookup, as through the API. What is sent is the ecosystem, the package name and the version, and
+nothing else.
+
+## Run it locally
+
+```
+ATTESTARI_API_KEY=att_live_... uvx attestari-mcp
+```
+
+It speaks MCP over standard input and output and opens no port. In an MCP client's configuration:
+
+```json
+{
+  "mcpServers": {
+    "attestari": {
+      "command": "uvx",
+      "args": ["attestari-mcp"],
+      "env": { "ATTESTARI_API_KEY": "att_live_..." }
+    }
+  }
+}
+```
+
+`ATTESTARI_API_URL` changes the lookup API's address (default `https://api.attestari.ai`).
+
+## Tools
+
+- `lookup_package`: one package (`ecosystem`: `npm` or `pypi`; `name`; `version`, or none for the latest version
+  examined).
+- `lookup_packages`: up to 20 packages at once, each counted as one lookup.
+
+Both only read. Each answer says its outcome: `graded`, `not_gradeable` (examined, no opinion given), `not_a_server`
+(out of scope), `not_examined`, `under_re_examination`, `refused` (the key, the plan or a limit) or `unavailable`.
+
+## What the answer carries from a package
+
+Its name, its version, and the file paths of its findings and capabilities with their line numbers. No excerpt of a
+package's code or text is passed on: text written by a package's publisher never reaches the agent through this
+server.
+
+## Licence
+
+MIT.

attestari_mcp-0.1.0/README.md

@@ -0,0 +1,52 @@
+# attestari-mcp
+
+<!-- mcp-name: ai.attestari/attestari -->
+
+Attestari's verdict on an npm or PyPI package version, over the Model Context Protocol. The answer is the Attestari
+lookup API's: the grade, the decision, the confirmed findings by reason code and place, and the methodology version
+and document hash the decision cites. "Not examined" is its own answer and is never a sign that a package is safe.
+
+Every lookup needs an Attestari API key (the Developer tier and above, https://attestari.ai/pricing#line-2) and is
+counted as one lookup, as through the API. What is sent is the ecosystem, the package name and the version, and
+nothing else.
+
+## Run it locally
+
+```
+ATTESTARI_API_KEY=att_live_... uvx attestari-mcp
+```
+
+It speaks MCP over standard input and output and opens no port. In an MCP client's configuration:
+
+```json
+{
+  "mcpServers": {
+    "attestari": {
+      "command": "uvx",
+      "args": ["attestari-mcp"],
+      "env": { "ATTESTARI_API_KEY": "att_live_..." }
+    }
+  }
+}
+```
+
+`ATTESTARI_API_URL` changes the lookup API's address (default `https://api.attestari.ai`).
+
+## Tools
+
+- `lookup_package`: one package (`ecosystem`: `npm` or `pypi`; `name`; `version`, or none for the latest version
+  examined).
+- `lookup_packages`: up to 20 packages at once, each counted as one lookup.
+
+Both only read. Each answer says its outcome: `graded`, `not_gradeable` (examined, no opinion given), `not_a_server`
+(out of scope), `not_examined`, `under_re_examination`, `refused` (the key, the plan or a limit) or `unavailable`.
+
+## What the answer carries from a package
+
+Its name, its version, and the file paths of its findings and capabilities with their line numbers. No excerpt of a
+package's code or text is passed on: text written by a package's publisher never reaches the agent through this
+server.
+
+## Licence
+
+MIT.

attestari_mcp-0.1.0/attestari_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""attestari-mcp: Attestari's verdict on an npm or PyPI package version, over the Model Context Protocol."""
+
+__version__ = "0.1.0"

attestari_mcp-0.1.0/attestari_mcp/address.py

@@ -0,0 +1,17 @@
+"""The agent's address, as the MCP server's balancer saw it (docs/app.attestari.ai/phase-1-mcp-plan.md, decision 11).
+
+The same rule the lookup API reads its own callers' addresses by (attestari_api/app.py, `client_address`, with the
+last entry): Google's front end writes the connection's address last in `X-Forwarded-For`, after anything the caller
+sent, so a prefix the caller wrote buys nothing; through a load balancer the list ends `<client>,<balancer>`, and a
+last entry that is one of the balancer's own addresses is set aside, so the entry before it is the client's. The
+lookup API then counts the call against this address (an IPv6 one by its /64), never against the MCP server's.
+"""
+
+from __future__ import annotations
+
+
+def agent_address(forwarded_for: str | None, edge: frozenset[str], fallback: str = "unknown") -> str:
+    forwarded = [p.strip() for p in (forwarded_for or "").split(",") if p.strip()]
+    if len(forwarded) > 1 and forwarded[-1] in edge:
+        forwarded = forwarded[:-1]
+    return forwarded[-1] if forwarded else fallback

attestari_mcp-0.1.0/attestari_mcp/answer.py

@@ -0,0 +1,240 @@
+"""What a tool answers: a projection of the lookup API's answer (docs/app.attestari.ai/mcp-threat-model.md, T8).
+
+The lookup API's full verdict carries a package's own bytes in a few places: each capability's `excerpt` (the call as
+written) and `target`, the delegation's `module` and `spec`. A tool's answer leaves every one of them out. What it
+keeps from a package is the package's name and version and the file paths of its findings and capabilities, each with
+its line; every other text in it is Attestari's (rule texts, reason codes, the sentences below). An agent reading the
+answer reads nothing a package's publisher wrote but names, versions and paths.
+
+"Not examined" is an outcome of its own, and so are a refusal and an outage: no answer is ever an empty success.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Literal, cast
+
+from pydantic import BaseModel, Field
+
+Outcome = Literal["graded", "not_gradeable", "not_a_server", "not_examined", "under_re_examination", "refused", "unavailable"]
+
+SENTENCES: dict[str, str] = {
+    "graded": "Examined and graded under the methodology named.",
+    "not_gradeable": "Examined, but not graded: a guard of the methodology failed and no opinion is given. Not graded is never safe.",
+    "not_a_server": "Examined: this package is not an MCP server, which is outside what Attestari grades.",
+    "not_examined": "Attestari has not examined this package version. Not examined is never safe.",
+    "under_re_examination": "The decision is under re-examination: no grade is served until it is decided again.",
+}
+# The refusals the lookup API names, in Attestari's words.
+REFUSALS: dict[str, str] = {
+    "key_required": "The lookup API needs an Attestari API key.",
+    "invalid_key": "The Attestari API key was refused: it does not exist or was revoked.",
+    "subscription_required": "The organization's plan includes no lookups.",
+    "trial_allowance_reached": "The trial's lookups for this month are used; lookups resume when the plan is paid or next month.",
+    "rate_limited": "Too many lookups a minute for this key or address; retry after the time given.",
+    "bad_request": "The package was not asked for as the lookup API reads it.",
+}
+UNAVAILABLE = "The Attestari lookup API did not answer just now; nothing is known of this package from this call."
+# As the lookup API reads them (attestari_api/app.py: SEVERITY_ORDER, MDT, MDT_CATEGORIES).
+SEVERITY_ORDER = ("info", "low", "medium", "high")
+MDT = "model_directed_text"
+MDT_CATEGORIES = ("exfiltrate_data", "conceal_from_user", "override_user")
+
+
+class Methodology(BaseModel):
+    version: str
+    document_sha256: str
+    url: str
+
+
+class FindingRef(BaseModel):
+    check: str = Field(description="the check that made the finding (Attestari's name)")
+    severity: str
+    decision: str = Field(description="confirmed, noted, or withdrawn_on_appeal")
+    rule: str = Field(description="the rule, in Attestari's words")
+    location: str | None = Field(description="file:line in the package (the path is the package's)")
+    evidence_id: str = Field(description="SHA-256 of the evidence the finding was verified against")
+
+
+class CapabilityRef(BaseModel):
+    kind: str = Field(description="network, filesystem, process, environment, credentials or remote_code")
+    tag: str
+    location: str = Field(description="file:line in the package (the path is the package's)")
+    evidence_id: str
+
+
+class PackageAnswer(BaseModel):
+    ecosystem: str
+    name: str
+    version: str | None = Field(description="the version the answer is about; the version asked for when none was examined")
+    outcome: Outcome
+    summary: str = Field(description="the outcome in one sentence, in Attestari's words")
+    grade: str | None = Field(default=None, description="A, B, C or F when graded; never given otherwise")
+    reason_codes: list[str] = Field(default_factory=list[str])
+    finding_count: int | None = Field(default=None, description="confirmed findings")
+    highest_severity: str | None = None
+    classes: list[str] = Field(default_factory=list[str], description="the model-directed categories of the confirmed findings")
+    findings: list[FindingRef] = Field(default_factory=list[FindingRef])
+    capabilities: list[CapabilityRef] = Field(default_factory=list[CapabilityRef], description="what the source can reach; never a finding")
+    evidence_available_on: str | None = Field(default=None, description="when a high or medium finding's evidence is published (day 30)")
+    methodology: Methodology | None = None
+    run_id: str | None = None
+    decided_at: str | None = None
+    notice: str | None = Field(default=None, description="set when the newest examination was incomplete on Attestari's side")
+    retry_after: int | None = Field(default=None, description="seconds, when the lookup was refused for a rate")
+
+
+def _dict(value: Any) -> dict[str, Any]:
+    return cast(dict[str, Any], value) if isinstance(value, dict) else {}
+
+
+def _dicts(value: Any) -> list[dict[str, Any]]:
+    return [cast(dict[str, Any], v) for v in cast(list[Any], value) if isinstance(v, dict)] if isinstance(value, list) else []
+
+
+def _strs(value: Any) -> list[str]:
+    return [str(v) for v in cast(list[Any], value)] if isinstance(value, list) else []
+
+
+def _str(value: Any) -> str | None:
+    return value if isinstance(value, str) else None
+
+
+def _int(value: Any) -> int | None:
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def _methodology(value: Any) -> Methodology | None:
+    m = _dict(value)
+    version, sha, url = _str(m.get("version")), _str(m.get("document_sha256")), _str(m.get("url"))
+    return Methodology(version=version, document_sha256=sha, url=url) if version and sha and url else None
+
+
+def project(status: int, body: Any, ecosystem: str, name: str, version: str | None) -> PackageAnswer:
+    """The tool's answer to one lookup, from the lookup API's status and body. Unknown shapes are an outage, never a
+    success: what cannot be read is not passed on."""
+    said = _dict(body)
+    kind = said.get("status")
+
+    def answer(outcome: Outcome, summary: str, served: str | None = version) -> PackageAnswer:
+        return PackageAnswer(ecosystem=ecosystem, name=name, version=served, outcome=outcome, summary=summary)
+
+    if status == 404 and kind == "not_examined":
+        return answer("not_examined", SENTENCES["not_examined"])
+    if status in (400, 401, 402, 403, 422, 429) or kind in REFUSALS:
+        reason = kind if isinstance(kind, str) and kind in REFUSALS else ("rate_limited" if status == 429 else "bad_request")
+        return answer("refused", REFUSALS[reason]).model_copy(
+            update={"reason_codes": [reason], "retry_after": _int(said.get("retry_after"))}
+        )
+    subject = _dict(said.get("subject"))
+    if status != 200 or not subject:
+        return answer("unavailable", UNAVAILABLE)
+
+    served = _str(subject.get("version")) or version
+    methodology = _methodology(said.get("methodology"))
+    if kind == "under_re_examination":
+        return answer("under_re_examination", SENTENCES["under_re_examination"], served).model_copy(
+            update={"methodology": methodology, "run_id": _str(said.get("run_id")), "decided_at": _str(said.get("decided_at"))}
+        )
+    decision = said.get("decision")
+    if kind != "examined" or decision not in ("graded", "not_gradeable", "not_a_server"):
+        return answer("unavailable", UNAVAILABLE)
+
+    outcome = cast(Outcome, decision)
+    if not _vouched(
+        answer(outcome, SENTENCES[outcome], served).model_copy(
+            update={"grade": _str(said.get("grade")) if outcome == "graded" else None, "methodology": methodology}
+        ),
+        subject,
+        ecosystem,
+        name,
+        version,
+    ):
+        return answer("unavailable", UNAVAILABLE)
+    base = answer(outcome, SENTENCES[outcome], served).model_copy(
+        update={
+            "grade": _str(said.get("grade")) if outcome == "graded" else None,
+            "methodology": methodology,
+            "notice": _str(said.get("notice")),
+        }
+    )
+
+    if isinstance(said.get("findings"), list):
+        # The full verdict, projected: every field that carries a package's own bytes is left out (T8).
+        findings = _dicts(said.get("findings"))
+        confirmed = [f for f in findings if f.get("decision") == "confirmed"]
+        severities = [str(f.get("severity")) for f in confirmed]
+        provenance = _dict(said.get("provenance"))
+        return base.model_copy(
+            update={
+                "reason_codes": _strs(said.get("reason_codes")),
+                "finding_count": len(confirmed),
+                "highest_severity": max(severities, key=_rank) if severities else None,
+                "classes": sorted({t for f in confirmed if f.get("check") == MDT for t in _strs(f.get("tags")) if t in MDT_CATEGORIES}),
+                "findings": [
+                    FindingRef(
+                        check=str(f.get("check")),
+                        severity=str(f.get("severity")),
+                        decision=str(f.get("decision")),
+                        rule=str(f.get("rule")),
+                        location=_place(f.get("location")),
+                        evidence_id=str(f.get("evidence_id")),
+                    )
+                    for f in findings
+                ],
+                "capabilities": [
+                    CapabilityRef(
+                        kind=str(c.get("kind")),
+                        tag=str(c.get("tag")),
+                        location=_place(c.get("location")) or "",
+                        evidence_id=str(c.get("evidence_id")),
+                    )
+                    for c in _dicts(said.get("capabilities"))
+                ],
+                "run_id": _str(provenance.get("run_id")),
+                "decided_at": _str(provenance.get("decided_at")),
+            }
+        )
+
+    # The summary: what a key whose evidence waits for day 30 is answered, with the date.
+    return base.model_copy(
+        update={
+            "finding_count": _int(said.get("finding_count")),
+            "highest_severity": _str(said.get("highest_severity")),
+            "classes": _strs(said.get("classes")),
+            "evidence_available_on": _str(said.get("evidence_available_on")),
+            "decided_at": _str(said.get("decided_at")),
+        }
+    )
+
+
+GRADES = ("A", "B", "C", "F")
+PLACE_AT_MOST = 300
+_CONTROL = re.compile(r"[\x00-\x1f\x7f]")
+
+
+def _place(value: Any) -> str | None:
+    """A file:line from a package: its publisher's text, bounded and without control characters (M-12)."""
+    text = _str(value)
+    return None if text is None else _CONTROL.sub("", text)[:PLACE_AT_MOST]
+
+
+def _normal(ecosystem: str, name: str) -> str:
+    return re.sub(r"[-_.]+", "-", name).lower() if ecosystem == "pypi" else name
+
+
+def _vouched(answer: PackageAnswer, subject: dict[str, Any], ecosystem: str, name: str, version: str | None) -> bool:
+    """What a "graded" answer must hold before it is passed on (M-5): a grade of the ladder, the methodology, and the
+    package and version asked about."""
+    said_name, said_version = _str(subject.get("name")), _str(subject.get("version"))
+    if said_name is None or _normal(ecosystem, said_name) != _normal(ecosystem, name) or subject.get("ecosystem") != ecosystem:
+        return False
+    if version is not None and said_version != version:
+        return False
+    if answer.outcome == "graded" and (answer.grade not in GRADES or answer.methodology is None):
+        return False
+    return answer.methodology is not None
+
+
+def _rank(severity: str) -> int:
+    return SEVERITY_ORDER.index(severity) if severity in SEVERITY_ORDER else len(SEVERITY_ORDER)

attestari_mcp-0.1.0/attestari_mcp/lookup.py

@@ -0,0 +1,182 @@
+"""Asking the lookup API (https://api.attestari.ai) about a package, and nothing else.
+
+Two ways, one for each way the server runs:
+
+- **Direct** (the package run locally, over stdio): the customer's key in `Authorization`, as a program of theirs
+  would send it. The lookup API counts and limits the call as any keyed call, against the customer's own address.
+- **On an agent's behalf** (the remote server at mcp.attestari.ai; plan decision 11): the MCP server's own Google
+  identity token in `Authorization`, and the agent's key (`Attestari-Agent: key att_live_...`) and address
+  (`Attestari-Agent-Address`) beside it. The lookup API believes those two headers from the MCP server's service
+  account alone, and every bucket it then takes is the agent's: its key's, or its address's for a key refused or not
+  yet remembered. The MCP server's own address is charged nothing.
+
+What is sent is the ecosystem, the name and the version (price book line 2). Nothing here logs a key or a token.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+import re
+import time
+from dataclasses import dataclass
+from typing import Any, Protocol
+from urllib.parse import quote
+
+import httpx2
+
+from attestari_mcp import __version__
+from attestari_mcp.answer import PackageAnswer, project
+
+KEY = re.compile(r"^att_live_[0-9A-Za-z]{43}$")
+# What the lookup API can be asked about, checked before anything is sent: a name or version of another shape is
+# answered "refused" here and never reaches the API.
+# npm's own rule (MCP review M-4): no name or scope begins with "." or "_", so no segment is "." or "..".
+NPM_NAME = re.compile(r"^(@[A-Za-z0-9~-][A-Za-z0-9._~-]{0,212}/)?[A-Za-z0-9~-][A-Za-z0-9._~-]{0,213}$")
+PYPI_NAME = re.compile(r"^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,198}[A-Za-z0-9])?$")
+VERSION = re.compile(r"^[A-Za-z0-9][A-Za-z0-9.+_!-]{0,99}$")
+ECOSYSTEMS = ("npm", "pypi")
+AT_ONCE = 4
+TIMEOUT_SECONDS = 10.0
+METADATA_IDENTITY_URL = "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity"
+TOKEN_MARGIN_SECONDS = 300.0
+# A refusal that names the key, not the package: the rest of a batch is answered the same without being sent (M-1).
+KEY_REFUSALS = ("key_required", "invalid_key", "subscription_required", "trial_allowance_reached")
+LOCAL_HOSTS = ("localhost", "127.0.0.1", "::1")
+
+log = logging.getLogger("attestari_mcp")
+
+
+@dataclass(frozen=True)
+class Direct:
+    key: str
+
+
+@dataclass(frozen=True)
+class OnBehalf:
+    """`agent` is what the lookup API is told the call is for: `key att_live_...` (and, from milestone 1.3, `grant
+    <key row id>`); `address` is the agent's address as the MCP server's balancer saw it."""
+
+    agent: str
+    address: str
+
+
+Credential = Direct | OnBehalf
+
+
+class Identity(Protocol):
+    async def token(self) -> str: ...
+
+
+def path_of(ecosystem: str, name: str, version: str | None) -> str | None:
+    """The lookup API's path for the package, or None when the package cannot be one of its ecosystem's."""
+    if ecosystem not in ECOSYSTEMS or len(name) > 214:
+        return None
+    if not (NPM_NAME if ecosystem == "npm" else PYPI_NAME).match(name):
+        return None
+    if version is not None and not VERSION.match(version):
+        return None
+    # A scoped npm name keeps its one slash: the API reads /v1/verdict/npm/@scope/name[/version].
+    path = f"/v1/verdict/{ecosystem}/" + "/".join(quote(part, safe="@") for part in name.split("/"))
+    path = path if version is None else f"{path}/{quote(version, safe='')}"
+    # The path the HTTP client will send is the path built, or nothing is sent (M-4).
+    return path if httpx2.URL("https://lookup.invalid" + path).raw_path.decode("ascii") == path else None
+
+
+def secure_base(url: str) -> bool:
+    """The lookup API's address takes a key only over https, or plain http to this machine (M-11)."""
+    parsed = httpx2.URL(url)
+    return parsed.scheme == "https" or (parsed.scheme == "http" and parsed.host in LOCAL_HOSTS)
+
+
+class Lookup:
+    def __init__(self, base_url: str, http: httpx2.AsyncClient, identity: Identity | None = None) -> None:
+        if not secure_base(base_url):
+            raise ValueError("the lookup API's address must be https")
+        self.base_url = base_url.rstrip("/")
+        self.http = http
+        self.identity = identity
+
+    async def one(self, ecosystem: str, name: str, version: str | None, credential: Credential) -> PackageAnswer:
+        path = path_of(ecosystem, name, version)
+        if path is None:
+            return project(400, {"status": "bad_request"}, ecosystem, name, version)
+        headers = {"Accept": "application/json", "User-Agent": f"attestari-mcp/{__version__}"}
+        if isinstance(credential, Direct):
+            headers["Authorization"] = f"Bearer {credential.key}"
+        else:
+            if self.identity is None:
+                return project(503, None, ecosystem, name, version)
+            try:
+                headers["Authorization"] = f"Bearer {await self.identity.token()}"
+            except (httpx2.HTTPError, ValueError, KeyError):
+                return project(503, None, ecosystem, name, version)
+            headers["Attestari-Agent"] = credential.agent
+            headers["Attestari-Agent-Address"] = credential.address
+        try:
+            answer = await self.http.get(self.base_url + path, headers=headers, timeout=TIMEOUT_SECONDS)
+        except httpx2.HTTPError:
+            return project(503, None, ecosystem, name, version)
+        try:
+            body: Any = answer.json()
+        except ValueError:
+            body = None
+        if isinstance(credential, OnBehalf) and answer.status_code == 400:
+            # The lookup API refused the MCP server's own call: a fault of ours, never the agent's request (M-6).
+            log.error(json.dumps({"message": "the lookup API refused the MCP server's call on an agent's behalf", "status": 400}))
+            return project(503, None, ecosystem, name, version)
+        return project(answer.status_code, body, ecosystem, name, version)
+
+    async def many(self, asked: list[tuple[str, str, str | None]], credential: Credential) -> list[PackageAnswer]:
+        """Each package one lookup, a few at a time, answered in the order asked. The first is asked alone: when the
+        key itself is refused, the rest are answered the same and never sent (M-1)."""
+        if not asked:
+            return []
+        first = await self.one(*asked[0], credential)
+        refused = [r for r in first.reason_codes if r in KEY_REFUSALS] if first.outcome == "refused" else []
+        if refused:
+            return [first] + [project(401, {"status": refused[0]}, ecosystem, name, version) for ecosystem, name, version in asked[1:]]
+        gate = asyncio.Semaphore(AT_ONCE)
+
+        async def each(one: tuple[str, str, str | None]) -> PackageAnswer:
+            async with gate:
+                return await self.one(*one, credential)
+
+        return [first, *await asyncio.gather(*(each(one) for one in asked[1:]))]
+
+
+class MetadataIdentity:
+    """The MCP server's own Google identity token for the lookup API (Cloud Run's metadata server), kept until five
+    minutes before it expires."""
+
+    def __init__(self, audience: str, http: httpx2.AsyncClient) -> None:
+        self.audience = audience
+        self.http = http
+        self._token: str | None = None
+        self._expires = 0.0
+        self._lock = asyncio.Lock()
+
+    async def token(self) -> str:
+        async with self._lock:
+            if self._token is None or time.time() > self._expires - TOKEN_MARGIN_SECONDS:
+                answer = await self.http.get(
+                    METADATA_IDENTITY_URL,
+                    params={"audience": self.audience, "format": "full"},
+                    headers={"Metadata-Flavor": "Google"},
+                    timeout=TIMEOUT_SECONDS,
+                )
+                answer.raise_for_status()
+                self._token = answer.text.strip()
+                self._expires = float(_claims(self._token)["exp"])
+            return self._token
+
+
+def _claims(token: str) -> dict[str, Any]:
+    """The payload of a JWT, read without checking it: only to know when our own token expires."""
+    payload = token.split(".")[1]
+    claims: Any = json.loads(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))
+    if not isinstance(claims, dict):
+        raise ValueError("not a token")
+    return claims  # pyright: ignore[reportUnknownVariableType]